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

package/dist/internal/contracts/tenant-source-document.js

@@ -0,0 +1,38 @@
+/** 原生来源投影保留抽取结构，不借用 Project 身份或知识审核状态。 */
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { richDocumentSchema, validateRichDocumentContent } from './rich-document.js';
+import { materialTenantIdSchema } from './material-context.js';
+import { tenantResourceRefs, parseTenantResourceRef, tenantStorageKey } from './resource-scope.js';
+import { sha256Schema, stableUriSchema } from './common.js';
+export const TENANT_SOURCE_DOCUMENT_MEDIA_TYPE = 'application/vnd.knowledge-v2.tenant-source-document+json';
+const base = z.object({ ...richDocumentSchema.shape }).omit({ projectKey: true, projectRef: true, format: true, role: true, publicationProfile: true });
+export const tenantSourceDocumentSchema = base.extend({ format: z.literal('TENANT_RICH_SOURCE_DOCUMENT_V1'), role: z.literal('SOURCE_MIRROR'), tenantId: materialTenantIdSchema }).strict().superRefine((v, ctx) => {
+    validateRichDocumentContent(v, ctx);
+    const issue = (message) => ctx.addIssue({ code: 'custom', message });
+    if (v.sourceEvidenceRefs.length !== 1 || v.sourceEvidenceRefs[0] !== v.primarySourceEvidenceRef)
+        issue('Source mirror requires one exact parent');
+    const key = tenantStorageKey(v.tenantId), refs = [...v.sourceEvidenceRefs, ...v.mediaEvidenceRefs];
+    if (new Set(refs).size !== refs.length || refs.some(ref => { const p = parseTenantResourceRef(ref); return !p || p.storageKey !== key || p.resourceType !== 'evidence'; }))
+        issue('Source/media must retain exact Tenant Evidence identity');
+    const media = new Set(v.mediaEvidenceRefs);
+    for (const b of v.blocks) {
+        if ('availability' in b && (b.evidenceRef && (!media.has(b.evidenceRef) || b.mediaRef !== b.evidenceRef) || b.kind === 'VIDEO' && b.posterEvidenceRef && !media.has(b.posterEvidenceRef)))
+            issue('Media must identify a declared Evidence');
+    }
+});
+export function tenantSourceDocumentIdentity(tenantId, parentRef, documentContentHash) {
+    const parent = parseTenantResourceRef(parentRef);
+    if (!parent || parent.storageKey !== tenantStorageKey(tenantId) || parent.resourceType !== 'evidence')
+        throw new Error('TENANT_DERIVATION_PARENT_INVALID');
+    const resourceId = 'doc_' + createHash('sha256').update(JSON.stringify([parentRef, sha256Schema.parse(documentContentHash)])).digest('hex');
+    return { resourceId, ...tenantResourceRefs({ tenantId, resourceType: 'source_document', resourceId, version: 1 }) };
+}
+export function tenantSourceMediaIdentity(tenantId, parentRef, kind, url) {
+    stableUriSchema.parse(url);
+    const parent = parseTenantResourceRef(parentRef);
+    if (!parent || parent.storageKey !== tenantStorageKey(tenantId) || parent.resourceType !== 'evidence' || !['IMAGE', 'VIDEO', 'AUDIO'].includes(kind))
+        throw new Error('TENANT_DERIVATION_PARENT_INVALID');
+    const resourceId = 'media_' + createHash('sha256').update(JSON.stringify([parentRef, kind, url])).digest('hex');
+    return { resourceId, ...tenantResourceRefs({ tenantId, resourceType: 'evidence', resourceId, version: 1 }) };
+}

package/dist/internal/contracts/tenant-source-lease.js

@@ -0,0 +1,5 @@
+/** 预算和计划修订不能为同一 Tenant Source 创建并行获取 owner；复用 RuntimeStore 租约。 */
+import { createHash } from 'node:crypto';
+import { materialTenantIdSchema } from './material-context.js';
+import { tenantSourceIdSchema } from './tenant-source.js';
+export function tenantSourceLeaseKey(tenantId, sourceId) { return 'tenant-source:' + createHash('sha256').update(JSON.stringify(['TENANT_SOURCE_LEASE_V1', materialTenantIdSchema.parse(tenantId), tenantSourceIdSchema.parse(sourceId)])).digest('hex'); }

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

@@ -0,0 +1,83 @@
+/** 来源获取语义不包含用途、Project、调度启用或秘密；同 URL 不代表同一次获取权限。 */
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { acquisitionTargetSchema } from './project-intent.js';
+import { accessClassificationSchema, sha256Schema, stableUriSchema } from './common.js';
+import { materialTenantIdSchema } from './material-context.js';
+import { tenantStorageKey } from './resource-scope.js';
+export const tenantSourceIdSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/);
+export const tenantSourceCredentialSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('PUBLIC') }).strict(),
+    z.object({ type: z.literal('BOUND'), bindingRef: stableUriSchema, revision: sha256Schema }).strict(),
+]);
+/** Shared Source/configuration rule: secrets never become acquisition locator parameters. */
+export const isTenantSourceCredentialParameter = (key) => /^(?:password|passwd|secret|cookie|authorization|auth|token|access[_-]?token|refresh[_-]?token|api[_-]?key|signature|x-amz-signature|x-goog-signature)$/i.test(key);
+export const tenantSourceSemanticsSchema = z.object({
+    target: acquisitionTargetSchema,
+    credential: tenantSourceCredentialSchema,
+    executionBinding: z.object({ bindingRef: stableUriSchema, revision: sha256Schema }).strict().nullable().default(null),
+    access: accessClassificationSchema,
+    sourcePolicy: z.object({ ref: stableUriSchema, revision: sha256Schema, acquisition: z.enum(['ALLOW', 'DENY']), propagation: z.enum(['TENANT_ONLY', 'SHARE_ALLOWED', 'PUBLIC_ALLOWED']) }).strict(),
+    region: z.string().trim().min(1).max(128).nullable(),
+    representation: z.object({ format: z.enum(['RAW', 'RICH_DOCUMENT_V1']), extractor: z.object({ id: z.string().trim().min(1).max(128), version: z.string().trim().min(1).max(128) }).strict().nullable() }).strict(),
+}).strict().superRefine((value, ctx) => {
+    if ((value.representation.format === 'RAW') !== (value.representation.extractor === null))
+        ctx.addIssue({ code: 'custom', path: ['representation'], message: 'Derived representation requires its exact registered extractor' });
+    if ((value.target.kind !== 'URL' || value.credential.type === 'BOUND') && value.executionBinding === null)
+        ctx.addIssue({ code: 'custom', path: ['executionBinding'], message: 'FILE, EXECUTOR and authenticated acquisition require an exact runtime binding revision' });
+    if (value.target.kind === 'URL') {
+        const url = new URL(value.target.locator);
+        if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || value.target.locator.length > 2048)
+            ctx.addIssue({ code: 'custom', path: ['target'], message: 'URL target must use bounded HTTP without embedded credentials' });
+        if ([...url.searchParams.keys()].some(isTenantSourceCredentialParameter))
+            ctx.addIssue({ code: 'custom', path: ['target'], message: 'Credential query parameters belong in a runtime binding' });
+    }
+    if (value.target.kind === 'EXECUTOR' && Object.keys(value.target.parameters).some(key => /(?:password|secret|cookie|authorization|access[_-]?token|refresh[_-]?token)/i.test(key)))
+        ctx.addIssue({ code: 'custom', path: ['target', 'parameters'], message: 'Secrets belong in a runtime credential binding' });
+});
+export const tenantSourceBasisSchema = z.object({
+    schemaVersion: z.literal(1), tenantId: materialTenantIdSchema, sourceId: tenantSourceIdSchema,
+    title: z.string().trim().min(1).max(512), semantics: tenantSourceSemanticsSchema,
+}).strict().superRefine((value, ctx) => {
+    if (value.semantics.credential.type === 'BOUND') {
+        const prefix = `tenant-credential://${tenantStorageKey(value.tenantId)}/`, ref = value.semantics.credential.bindingRef;
+        if (!ref.startsWith(prefix) || !tenantSourceIdSchema.safeParse(ref.slice(prefix.length)).success)
+            ctx.addIssue({ code: 'custom', path: ['semantics', 'credential', 'bindingRef'], message: 'Credential reference must belong to the exact Tenant' });
+    }
+    if (value.semantics.executionBinding !== null) {
+        const prefix = `tenant-execution://${tenantStorageKey(value.tenantId)}/`, ref = value.semantics.executionBinding.bindingRef;
+        if (!ref.startsWith(prefix) || !tenantSourceIdSchema.safeParse(ref.slice(prefix.length)).success)
+            ctx.addIssue({ code: 'custom', path: ['semantics', 'executionBinding', 'bindingRef'], message: 'Execution binding must belong to the exact Tenant' });
+    }
+});
+export function tenantSourceRef(tenantId, sourceId) { return `tenant-source://${tenantStorageKey(tenantId)}/${tenantSourceIdSchema.parse(sourceId)}`; }
+export function parseTenantSourceRevisionRef(ref) {
+    const match = /^tenant-source:\/\/([a-f0-9]{64})\/([A-Za-z0-9][A-Za-z0-9._-]{0,127})\/v\/([a-f0-9]{64})$/.exec(ref);
+    return match ? { storageKey: match[1], sourceId: match[2], revision: `sha256:${match[3]}` } : null;
+}
+const canonical = (value) => { if (value === null || typeof value !== 'object')
+    return JSON.stringify(value); if (Array.isArray(value))
+    return '[' + value.map(canonical).join(',') + ']'; const row = value; return '{' + Object.keys(row).sort().map(key => JSON.stringify(key) + ':' + canonical(row[key])).join(',') + '}'; };
+const hash = (value) => 'sha256:' + createHash('sha256').update(canonical(value)).digest('hex');
+/** 已正规化 basis 的唯一指纹算法，canonical reader 与 Identity 关系校验共用。 */
+export function tenantSourceFingerprints(basis) {
+    const sourceRef = tenantSourceRef(basis.tenantId, basis.sourceId), revision = hash(basis);
+    return { sourceRef, revision, revisionRef: `${sourceRef}/v/${revision.slice(7)}`, semanticKey: hash({ tenantId: basis.tenantId, semantics: basis.semantics }), targetId: hash(basis.semantics.target) };
+}
+export const tenantSourceSnapshotSchema = tenantSourceBasisSchema.safeExtend({
+    sourceRef: stableUriSchema, revision: sha256Schema, revisionRef: stableUriSchema, semanticKey: sha256Schema, targetId: sha256Schema,
+}).strict().superRefine((value, ctx) => {
+    const ref = tenantSourceRef(value.tenantId, value.sourceId);
+    if (value.sourceRef !== ref || value.revisionRef !== `${ref}/v/${value.revision.slice(7)}`)
+        ctx.addIssue({ code: 'custom', path: ['revisionRef'], message: 'Source revision must retain exact Tenant and Source identity' });
+    if (value.semantics.target.kind === 'URL') {
+        const url = new URL(value.semantics.target.locator);
+        url.hash = '';
+        if (url.toString() !== value.semantics.target.locator)
+            ctx.addIssue({ code: 'custom', path: ['semantics', 'target'], message: 'Snapshot URL must be canonical' });
+    }
+    const { sourceRef, revision, revisionRef, semanticKey, targetId, ...basis } = value, expected = tenantSourceFingerprints(basis);
+    for (const key of ['sourceRef', 'revision', 'revisionRef', 'semanticKey', 'targetId'])
+        if (value[key] !== expected[key])
+            ctx.addIssue({ code: 'custom', path: [key], message: 'Source fingerprint mismatch' });
+});

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

@@ -0,0 +1,118 @@
+/** Tenant 网站采集意图；范围和内容要求不携带 Project 或执行权限。 */
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { isoDateTimeSchema, sha256Schema } from './common.js';
+import { materialTenantIdSchema } from './material-context.js';
+import { tenantStorageKey } from './resource-scope.js';
+import { knowledgeActorContextSchema } from './project-intent.js';
+import { isTenantSourceCredentialParameter } from './tenant-source.js';
+import { tenantCollectionCycleSchema, tenantCollectionMaxBytesSchema } from './tenant-collection.js';
+import { tenantCollectionRequestAuthoritySchema } from './tenant-collection-request.js';
+export const TENANT_WEB_SPEC_CAPABILITY = 'TENANT_WEB_COLLECTION_SPEC_V1';
+export const tenantWebUrlSchema = z.string().url().max(2048).superRefine((raw, ctx) => {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        ctx.addIssue({ code: 'custom', message: 'A valid HTTP URL is required' });
+        return;
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.hash || url.port || [...url.searchParams.keys()].some(isTenantSourceCredentialParameter))
+        ctx.addIssue({ code: 'custom', message: 'Public HTTP URL without credentials, nonstandard port or fragment required' });
+});
+const originSchema = tenantWebUrlSchema.superRefine((value, ctx) => { try {
+    if (new URL(value).origin === value)
+        return;
+}
+catch { /* Report a schema issue, never an arbitrary URL parser error. */ } ctx.addIssue({ code: 'custom', message: 'An exact HTTP origin is required' }); });
+const pathSchema = z.string().min(1).max(512).superRefine((value, ctx) => {
+    let decoded = '';
+    try {
+        decoded = decodeURIComponent(value);
+    }
+    catch { /* Invalid encoding fails closed below. */ }
+    if (!decoded.startsWith('/') || decoded.startsWith('//') || /[?#\\\x00-\x1f]/.test(decoded) || decoded.split('/').some(part => part === '.' || part === '..') || decoded.replace(/\/\*\*$/, '').includes('*'))
+        ctx.addIssue({ code: 'custom', message: 'Absolute path or terminal /** prefix required' });
+});
+export const tenantWebScopeSchema = z.object({
+    mode: z.enum(['SINGLE_PAGE', 'URL_LIST', 'SITE_SECTION', 'SITEMAP', 'FEED']),
+    allowedOrigins: z.array(originSchema).max(16).default([]),
+    includePaths: z.array(pathSchema).max(32).default([]),
+    excludePaths: z.array(pathSchema).max(32).default([]),
+    urls: z.array(tenantWebUrlSchema).max(64).default([]),
+    followPagination: z.boolean().default(false),
+    followDetailLinks: z.boolean().default(false),
+}).strict();
+const field = z.object({ name: z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,63}$/), type: z.enum(['string', 'number', 'boolean', 'object', 'array']), required: z.boolean().default(false) }).strict();
+export const tenantWebRequirementsSchema = z.object({
+    instruction: z.string().trim().min(1).max(4000),
+    fields: z.array(field).max(64).default([]),
+    outputs: z.array(z.enum(['RAW', 'DOCUMENT', 'RECORDS'])).min(1).max(3).default(['RAW', 'DOCUMENT']),
+    attachments: z.array(z.enum(['PDF', 'IMAGE', 'AUDIO', 'VIDEO', 'OTHER'])).max(5).default([]),
+}).strict().superRefine((value, ctx) => { if (new Set(value.fields.map(f => f.name)).size !== value.fields.length)
+    ctx.addIssue({ code: 'custom', message: 'Field names must be unique' }); });
+export const tenantWebDefaultLimits = { maxPages: 100, maxDepth: 3, maxResourceBytes: 16 * 1024 * 1024, maxTotalBytes: 64 * 1024 * 1024, maxRuntimeMs: 300000, maxInteractions: 100, maxFiles: 100 };
+export const tenantWebLimitsSchema = z.object({
+    maxPages: z.number().int().min(1).max(10000).default(100),
+    maxDepth: z.number().int().min(0).max(10).default(3),
+    maxResourceBytes: tenantCollectionMaxBytesSchema.default(16 * 1024 * 1024),
+    maxTotalBytes: z.number().int().min(1024).max(1024 * 1024 * 1024).default(64 * 1024 * 1024),
+    maxRuntimeMs: z.number().int().min(1000).max(900000).default(300000),
+    maxInteractions: z.number().int().min(0).max(1000).default(100),
+    maxFiles: z.number().int().min(0).max(1000).default(100),
+}).strict();
+export const tenantWebSpecSchema = z.object({
+    schemaVersion: z.literal(1), url: tenantWebUrlSchema, scope: tenantWebScopeSchema,
+    requirements: tenantWebRequirementsSchema, limits: tenantWebLimitsSchema.default(tenantWebDefaultLimits),
+    refresh: z.object({ mode: z.literal('ONCE') }).strict().default({ mode: 'ONCE' }),
+}).strict().superRefine((value, ctx) => {
+    try {
+        const origins = value.scope.allowedOrigins.length ? value.scope.allowedOrigins : [new URL(value.url).origin];
+        if (!origins.includes(new URL(value.url).origin) || value.scope.urls.some(url => !origins.includes(new URL(url).origin)))
+            ctx.addIssue({ code: 'custom', path: ['scope'], message: 'Entry and explicit targets must remain in the declared origins' });
+    }
+    catch {
+        ctx.addIssue({ code: 'custom', path: ['scope'], message: 'Valid entry and target URLs are required' });
+    }
+    if ((value.scope.mode === 'URL_LIST') !== (value.scope.urls.length > 0))
+        ctx.addIssue({ code: 'custom', path: ['scope', 'urls'], message: 'Only URL_LIST requires explicit URLs' });
+    if (value.scope.mode === 'SITE_SECTION' && value.scope.includePaths.length === 0)
+        ctx.addIssue({ code: 'custom', path: ['scope', 'includePaths'], message: 'A site section requires an explicit path boundary' });
+    if (value.scope.mode === 'SINGLE_PAGE' && (value.scope.followPagination || value.scope.followDetailLinks))
+        ctx.addIssue({ code: 'custom', path: ['scope'], message: 'Single page cannot enable discovery' });
+});
+export function tenantWebCanonical(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return '[' + value.map(tenantWebCanonical).join(',') + ']';
+    const row = value;
+    return '{' + Object.keys(row).filter(key => row[key] !== undefined).sort().map(key => JSON.stringify(key) + ':' + tenantWebCanonical(row[key])).join(',') + '}';
+}
+const hash = (value) => createHash('sha256').update(tenantWebCanonical(value)).digest('hex');
+export function tenantWebSpecRevision(spec) { return 'sha256:' + hash(tenantWebSpecSchema.parse(spec)); }
+export function tenantWebRequestKey(requestId) { return hash(tenantCollectionCycleSchema.parse(requestId)); }
+export function tenantWebJobRef(tenantId, requestId) { return `tenant-web-collection://${tenantStorageKey(tenantId)}/${tenantWebRequestKey(requestId)}`; }
+export const tenantWebJobRefSchema = z.string().regex(/^tenant-web-collection:\/\/[a-f0-9]{64}\/[a-f0-9]{64}$/);
+export const tenantWebIntentSchema = z.object({
+    schemaVersion: z.literal(1), tenantId: materialTenantIdSchema, requestId: tenantCollectionCycleSchema,
+    jobRef: tenantWebJobRefSchema, inputRevision: sha256Schema, specRevision: sha256Schema, requestedSpec: tenantWebSpecSchema, spec: tenantWebSpecSchema,
+    actor: knowledgeActorContextSchema, authority: tenantCollectionRequestAuthoritySchema, submittedAt: isoDateTimeSchema,
+}).strict().superRefine((value, ctx) => {
+    if (value.actor.tenantId !== value.tenantId || value.jobRef !== tenantWebJobRef(value.tenantId, value.requestId) || value.specRevision !== tenantWebSpecRevision(value.spec) || value.inputRevision !== tenantWebSpecRevision(value.requestedSpec))
+        ctx.addIssue({ code: 'custom', message: 'Intent must preserve exact Tenant and frozen specification identity' });
+    if (value.spec.limits.maxResourceBytes > Math.min(value.requestedSpec.limits.maxResourceBytes, value.requestedSpec.limits.maxTotalBytes) || tenantWebCanonical({ ...value.spec, limits: { ...value.spec.limits, maxResourceBytes: value.requestedSpec.limits.maxResourceBytes } }) !== tenantWebCanonical(value.requestedSpec))
+        ctx.addIssue({ code: 'custom', message: 'Intake may only narrow the resource byte limit' });
+});
+/** S1 仅证明意图持久化；不制造待采列表、原件、时效或准入成功。 */
+export const tenantWebSummarySchema = z.object({
+    requestId: tenantCollectionCycleSchema, jobRef: tenantWebJobRefSchema, specRevision: sha256Schema, submittedAt: isoDateTimeSchema,
+    phase: z.literal('WEB_INTENT_PERSISTED'), state: z.literal('ACCEPTED'), execution: z.literal('UNAVAILABLE'),
+    reason: z.literal('S2_NOT_IMPLEMENTED'), completion: z.null(), networkValidated: z.literal(false), budgetReserved: z.literal(false),
+    requirementsState: z.literal('DECLARED_NOT_EVALUATED'),
+    coverage: z.object({ state: z.literal('NOT_STARTED'), total: z.null(), discovered: z.literal(0), acquired: z.literal(0), extracted: z.literal(0), registered: z.literal(0) }).strict(),
+}).strict().superRefine((value, ctx) => {
+    if (new URL(value.jobRef).pathname !== `/${tenantWebRequestKey(value.requestId)}`)
+        ctx.addIssue({ code: 'custom', message: 'Summary request identity must match its exact intent reference' });
+});

package/dist/internal/contracts/tenant-web-content-plan.js

@@ -0,0 +1,39 @@
+/** Read-only extraction plans; no executable selectors, scripts, prompts or authority. */
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { tenantWebCanonical, tenantWebRequirementsSchema } from './tenant-web-collection.js';
+export const TENANT_WEB_CONTENT_CAPABILITY = 'TENANT_WEB_CONTENT_V1';
+export const TENANT_WEB_CONTENT_EXTRACTOR = { id: 'native-knowledge.web-content', version: '1.0.0' };
+// A deliberately bounded CSS subset: compound tag/id/classes, descendant and child only.
+const atom = '(?:[A-Za-z][A-Za-z0-9_-]*|\\*)?(?:[.#][A-Za-z_][A-Za-z0-9_-]*)*';
+export const tenantWebContentSelectorSchema = z.string().trim().min(1).max(256).refine(s => s.split(/\s*>\s*|\s+/).length <= 8 && new RegExp('^' + atom + '(?:\\s*>\\s*' + atom + '|\\s+' + atom + ')*$').test(s) && s.split(/\s*>\s*|\s+/).every(Boolean), 'Unsupported read-only selector').describe('Read-only CSS subset: tag/id/classes, descendant or child (>) only; max 8 segments, no pseudos or scripts');
+const rule = z.object({ name: z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,63}$/), selector: tenantWebContentSelectorSchema, value: z.enum(['TEXT', 'ATTRIBUTE', 'JSON']).default('TEXT'), attribute: z.enum(['href', 'src', 'content', 'datetime', 'value', 'title', 'alt']).nullable().default(null) }).strict().refine(v => (v.value === 'ATTRIBUTE') === (v.attribute !== null));
+export const tenantWebContentPlanSchema = z.object({ schemaVersion: z.literal(1), compiler: z.enum(['CALLER_PLAN_V1', 'BOUNDED_LANGUAGE_V1']), extractor: z.object({ id: z.literal('native-knowledge.web-content'), version: z.literal('1.0.0') }).strict(), body: z.boolean(), tables: z.boolean(), links: z.boolean(), recordSelector: tenantWebContentSelectorSchema.nullable(), fields: z.array(z.object({ ...tenantWebRequirementsSchema.shape.fields.unwrap().element.shape, ...rule.shape })).max(64), maxRecords: z.number().int().min(1).max(100).default(50) }).strict().superRefine((v, c) => { if (v.fields.some(f => (f.value === 'ATTRIBUTE') !== (f.attribute !== null)) || new Set(v.fields.map(f => f.name)).size !== v.fields.length)
+    c.addIssue({ code: 'custom', message: 'Invalid field rule' }); });
+export const tenantWebContentInputSchema = z.discriminatedUnion('mode', [z.object({ mode: z.literal('NATURAL_LANGUAGE') }).strict(), z.object({ mode: z.literal('COMPILED'), extractor: z.object({ id: z.literal('native-knowledge.web-content'), version: z.literal('1.0.0') }).strict().default(TENANT_WEB_CONTENT_EXTRACTOR), body: z.boolean().default(false), tables: z.boolean().default(false), links: z.boolean().default(false), recordSelector: tenantWebContentSelectorSchema.nullable().default(null), fields: z.array(rule).max(64).default([]), maxRecords: z.number().int().min(1).max(100).default(50) }).strict()]).describe('NATURAL_LANGUAGE supports bounded body/tables/links combinations in Chinese or English. Otherwise provide COMPILED rules; no model calls.');
+export function compileTenantWebContent(requirements, raw) {
+    const input = tenantWebContentInputSchema.parse(raw);
+    let body = false, tables = false, links = false;
+    if (input.mode === 'NATURAL_LANGUAGE') {
+        const words = requirements.instruction.toLowerCase().replace(/^(?:请)?(?:采集|提取|获取|collect|extract)\s*/, '').split(/\s*(?:、|，|,|和|及|与|\band\b)\s*/).map(w => w.trim()).filter(Boolean);
+        for (const word of words) {
+            if (['正文', 'body', 'text', 'body text'].includes(word))
+                body = true;
+            else if (['表格', 'tables', 'table'].includes(word))
+                tables = true;
+            else if (['链接', 'links'].includes(word))
+                links = true;
+            else
+                throw new Error('TENANT_WEB_SEMANTIC_COMPILER_UNAVAILABLE');
+        }
+        if (!words.length || requirements.fields.length)
+            throw new Error('TENANT_WEB_SEMANTIC_COMPILER_UNAVAILABLE');
+    }
+    const rules = input.mode === 'COMPILED' ? input.fields : [];
+    if (rules.length !== requirements.fields.length || rules.some(f => !requirements.fields.some(v => v.name === f.name)))
+        throw new Error('TENANT_WEB_CONTENT_FIELD_PLAN_REQUIRED');
+    if (requirements.outputs.includes('RECORDS') && !requirements.fields.length)
+        throw new Error('TENANT_WEB_CONTENT_FIELD_PLAN_REQUIRED');
+    return tenantWebContentPlanSchema.parse({ schemaVersion: 1, compiler: input.mode === 'COMPILED' ? 'CALLER_PLAN_V1' : 'BOUNDED_LANGUAGE_V1', extractor: TENANT_WEB_CONTENT_EXTRACTOR, body: input.mode === 'COMPILED' ? input.body : body, tables: input.mode === 'COMPILED' ? input.tables : tables, links: input.mode === 'COMPILED' ? input.links : links, recordSelector: input.mode === 'COMPILED' ? input.recordSelector : null, fields: requirements.fields.map(f => ({ ...f, ...rules.find(r => r.name === f.name) })), maxRecords: input.mode === 'COMPILED' ? input.maxRecords : 50 });
+}
+export const tenantWebContentRevision = (plan) => 'sha256:' + createHash('sha256').update(tenantWebCanonical(tenantWebContentPlanSchema.parse(plan))).digest('hex');

package/dist/internal/contracts/tenant-web-content-result.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { isoDateTimeSchema, sha256Schema } from './common.js';
+import { materialTenantIdSchema } from './material-context.js';
+import { tenantResourceRefSchema, parseTenantResourceRef, tenantStorageKey } from './resource-scope.js';
+import { tenantWebJobRefSchema, tenantWebUrlSchema } from './tenant-web-collection.js';
+import { tenantWebFieldResultSchema } from './tenant-web-results.js';
+import { TENANT_WEB_CONTENT_EXTRACTOR } from './tenant-web-content-plan.js';
+export const TENANT_WEB_CONTENT_MEDIA_TYPE = 'application/vnd.knowledge-v2.tenant-web-content+json';
+export const tenantWebContentDocumentSchema = z.object({ schemaVersion: z.literal(1), format: z.literal('TENANT_WEB_CONTENT_V1'), tenantId: materialTenantIdSchema, jobRef: tenantWebJobRefSchema, planRevision: sha256Schema, extractor: z.object({ id: z.literal(TENANT_WEB_CONTENT_EXTRACTOR.id), version: z.literal(TENANT_WEB_CONTENT_EXTRACTOR.version) }).strict(), dependencies: z.array(z.object({ id: z.string().min(1).max(128), version: z.string().min(1).max(64) }).strict()).min(1).max(8), propagation: z.literal('TENANT_ONLY'), reviewState: z.literal('UNREVIEWED'), parentEvidenceRef: tenantResourceRefSchema, sourceContentHash: sha256Schema, sourceByteLength: z.number().int().nonnegative(), sourceMediaType: z.string().min(1).max(256), sourceUri: tenantWebUrlSchema, observedAt: isoDateTimeSchema, extractedAt: isoDateTimeSchema, outputs: z.array(tenantWebFieldResultSchema).max(4), records: z.array(z.object({ ordinal: z.number().int().min(0).max(99), fields: z.array(tenantWebFieldResultSchema).max(64) }).strict()).max(100), gaps: z.array(z.string().regex(/^[A-Z][A-Z0-9_]{0,127}$/)).max(32) }).strict().superRefine((v, c) => {
+    const key = tenantStorageKey(v.tenantId), parent = parseTenantResourceRef(v.parentEvidenceRef);
+    if (parent?.storageKey !== key || parent.resourceType !== 'evidence' || new URL(v.jobRef).hostname !== key || [...v.outputs, ...v.records.flatMap(r => r.fields)].some(f => f.citations.some(cite => cite.evidenceRef !== v.parentEvidenceRef || cite.contentHash !== v.sourceContentHash)))
+        c.addIssue({ code: 'custom', message: 'Content must cite its exact Tenant original' });
+    if (v.records.some((r, i) => r.ordinal !== i))
+        c.addIssue({ code: 'custom', message: 'Record order must be exact' });
+});

package/dist/internal/contracts/tenant-web-content.js

@@ -0,0 +1,16 @@
+/** S4 composes frozen S3 acquisition with a separately versioned derived plan. */
+import { z } from 'zod';
+import { sha256Schema, isoDateTimeSchema } from './common.js';
+import { tenantWebDynamicJobSchema, tenantWebDynamicHeadSchema, tenantWebDynamicStatusSchema, tenantWebDynamicStatus } from './tenant-web-dynamic.js';
+import { tenantWebJobRefSchema } from './tenant-web-collection.js';
+import { tenantWebContentPlanSchema, tenantWebContentRevision } from './tenant-web-content-plan.js';
+import { tenantResourceRefSchema, parseTenantResourceRef } from './resource-scope.js';
+export const tenantWebContentJobSchema = z.object({ ...tenantWebDynamicJobSchema.shape, schemaVersion: z.literal(4), contentPlan: tenantWebContentPlanSchema, contentRevision: sha256Schema, retainedFrom: tenantWebJobRefSchema.nullable() }).strict().superRefine((v, c) => {
+    if (v.contentRevision !== tenantWebContentRevision(v.contentPlan) || v.retainedFrom && (v.retainedFrom === v.intent.jobRef || new URL(v.retainedFrom).hostname !== new URL(v.intent.jobRef).hostname) || JSON.stringify(v.contentPlan.fields.map(({ name, type, required }) => ({ name, type, required }))) !== JSON.stringify(v.intent.spec.requirements.fields))
+        c.addIssue({ code: 'custom', message: 'Frozen content plan identity mismatch' });
+});
+const count = z.number().int().min(0).max(22000);
+export const tenantWebContentHeadSchema = z.object({ schemaVersion: z.literal(1), seq: z.number().int().nonnegative(), cursor: count, variant: z.number().int().min(-1).max(100), processed: count, registered: count, missing: count, attempts: z.number().int().min(0).max(3), chargedBytes: z.number().int().nonnegative(), chargedMs: z.number().int().nonnegative(), reservation: z.object({ bytes: z.number().int().nonnegative(), ms: z.number().int().nonnegative() }).strict().nullable(), state: z.enum(['QUEUED', 'RUNNING', 'COMPLETE', 'PARTIAL']), gaps: z.array(z.string().regex(/^[A-Z][A-Z0-9_]{0,127}$/)).max(32), finishedAt: isoDateTimeSchema.nullable() }).strict().refine(v => v.registered <= v.processed && v.missing <= v.processed && (['COMPLETE', 'PARTIAL'].includes(v.state) === (v.finishedAt !== null)) && (v.state !== 'COMPLETE' || !v.gaps.length && !v.missing && !v.reservation) && (v.state !== 'PARTIAL' || v.gaps.length > 0));
+export const tenantWebContentOutcomeSchema = z.object({ schemaVersion: z.literal(1), index: count, ordinal: z.number().int().min(0).max(10999), variant: z.number().int().min(-1).max(100), documentRef: tenantResourceRefSchema.nullable(), gaps: tenantWebContentHeadSchema.shape.gaps }).strict().refine(v => !v.documentRef || parseTenantResourceRef(v.documentRef)?.resourceType === 'source_document');
+export const tenantWebContentStatusSchema = z.object({ ...tenantWebDynamicStatusSchema.shape, phase: z.enum(['DYNAMIC_ACQUISITION', 'CONTENT_DERIVATION']), requirementsState: z.enum(['PENDING', 'SATISFIED', 'PARTIAL']), contentRevision: sha256Schema, content: z.object({ processed: count, registered: count, missing: count, gaps: tenantWebContentHeadSchema.shape.gaps, compiler: tenantWebContentPlanSchema.shape.compiler, model: z.literal('DISABLED_NO_MODEL_CALLS') }).strict() }).strict();
+export function tenantWebContentStatus(job, a, h) { const base = tenantWebDynamicStatus(tenantWebDynamicJobSchema.parse({ schemaVersion: 3, intent: job.intent, policy: job.policy }), a), acquiring = !['COMPLETE', 'PARTIAL'].includes(a.state) && !job.retainedFrom; return tenantWebContentStatusSchema.parse({ ...base, contentRevision: job.contentRevision, phase: acquiring ? 'DYNAMIC_ACQUISITION' : 'CONTENT_DERIVATION', state: acquiring ? a.state : h.state, requirementsState: ['COMPLETE', 'PARTIAL'].includes(h.state) ? h.state === 'COMPLETE' && a.state === 'COMPLETE' ? 'SATISFIED' : 'PARTIAL' : 'PENDING', content: { processed: h.processed, registered: h.registered, missing: h.missing, gaps: h.gaps, compiler: job.contentPlan.compiler, model: 'DISABLED_NO_MODEL_CALLS' }, budget: { chargedBytes: (job.retainedFrom ? 0 : a.chargedBytes) + h.chargedBytes, chargedMs: (job.retainedFrom ? 0 : a.chargedMs) + h.chargedMs, conservativeReservation: !job.retainedFrom && a.reservation !== null || h.reservation !== null }, finishedAt: h.finishedAt, nextEligibleAt: acquiring ? a.notBefore : null }); }

package/dist/internal/contracts/tenant-web-crawl.js

@@ -0,0 +1,55 @@
+/** 可执行静态网站任务；独立于冻结的 S1 意图，Tenant 是唯一归属。 */
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { tenantStorageKey } from './resource-scope.js';
+import { tenantWebIntentSchema, tenantWebUrlSchema, tenantWebJobRefSchema, tenantWebCanonical } from './tenant-web-collection.js';
+import { tenantSourceSemanticsSchema } from './tenant-source.js';
+import { tenantCollectionCaptureSchema, tenantCollectionCycleSchema } from './tenant-collection.js';
+import { isoDateTimeSchema, sha256Schema } from './common.js';
+export const TENANT_WEB_CRAWL_CAPABILITY = 'TENANT_WEB_CRAWL_V1';
+export const tenantWebPolicySchema = tenantSourceSemanticsSchema.shape.sourcePolicy.refine(v => v.acquisition === 'ALLOW' && v.propagation === 'TENANT_ONLY');
+export const tenantWebCrawlSchema = z.object({ schemaVersion: z.literal(2), intent: tenantWebIntentSchema, policy: tenantWebPolicySchema }).strict();
+export function tenantWebAdmissionKey(tenantId, jobRef) { tenantWebJobRefSchema.parse(jobRef); if (new URL(jobRef).hostname !== tenantStorageKey(tenantId))
+    throw new Error('TENANT_WEB_SCOPE_FORBIDDEN'); return createHash('sha256').update(JSON.stringify(['TENANT_WEB_ADMISSION_V1', tenantId, jobRef])).digest('hex'); }
+export const tenantWebTargetSchema = z.object({ ordinal: z.number().int().min(0).max(9999), url: tenantWebUrlSchema, parent: tenantWebUrlSchema.nullable(), depth: z.number().int().min(0).max(10), role: z.enum(['PAGE', 'SITEMAP', 'FEED']) }).strict();
+export const tenantWebOutcomeSchema = z.object({ ordinal: tenantWebTargetSchema.shape.ordinal, batchId: z.string().regex(/^batch_[a-f0-9]{64}$/).nullable(), capture: tenantCollectionCaptureSchema.nullable(), registered: z.boolean(), errorCode: z.string().regex(/^[A-Z][A-Z0-9_]{0,127}$/).nullable(), reused: z.boolean() }).strict().refine(v => !v.registered || v.capture !== null);
+export const tenantWebHeadSchema = z.object({ schemaVersion: z.literal(1), seq: z.number().int().nonnegative(), queued: z.number().int().min(0).max(10000), cursor: z.number().int().min(0).max(10000), stage: z.enum(['ACQUIRE', 'DISCOVER']), after: z.number().int().nonnegative(), attempts: z.number().int().min(0).max(3), currentAcquired: z.boolean(), acquired: z.number().int().min(0).max(10000), registered: z.number().int().min(0).max(10000), chargedBytes: z.number().int().nonnegative(), chargedMs: z.number().int().nonnegative(), reservation: z.object({ bytes: z.number().int().nonnegative(), ms: z.number().int().nonnegative() }).strict().nullable(), gaps: z.array(z.string().regex(/^[A-Z][A-Z0-9_]{0,127}$/)).max(32), state: z.enum(['QUEUED', 'RUNNING', 'COMPLETE', 'PARTIAL']), finishedAt: isoDateTimeSchema.nullable(), notBefore: isoDateTimeSchema.nullable() }).strict().refine(v => v.cursor <= v.queued && v.registered <= v.acquired && v.acquired <= v.queued && (['COMPLETE', 'PARTIAL'].includes(v.state) === (v.finishedAt !== null)) && (!v.reservation || v.state === 'RUNNING' && v.chargedBytes >= v.reservation.bytes && v.chargedMs >= v.reservation.ms) && (!v.notBefore || v.state === 'RUNNING' && !v.reservation) && (v.state !== 'PARTIAL' || v.gaps.length > 0) && (v.state !== 'COMPLETE' || v.queued > 0 && v.cursor === v.queued && v.gaps.length === 0 && v.registered === v.queued && !v.reservation && !v.notBefore));
+export const tenantWebChildOwnerSchema = z.object({ schemaVersion: z.literal(1), jobRef: tenantWebJobRefSchema, ordinal: tenantWebTargetSchema.shape.ordinal, requestId: tenantCollectionCycleSchema, batchId: z.string().regex(/^batch_[a-f0-9]{64}$/) }).strict();
+export const tenantWebCrawlStatusSchema = z.object({ requestId: tenantCollectionCycleSchema, jobRef: tenantWebJobRefSchema, specRevision: sha256Schema, state: tenantWebHeadSchema.shape.state, phase: z.literal('STATIC_ACQUISITION'), requirementsState: z.literal('DECLARED_NOT_EVALUATED'), indexState: z.literal('NOT_EVALUATED'), coverage: z.object({ total: z.number().int().nonnegative().nullable(), discovered: z.number().int().nonnegative(), acquired: z.number().int().nonnegative(), registered: z.number().int().nonnegative(), pending: z.number().int().nonnegative(), gaps: tenantWebHeadSchema.shape.gaps }).strict(), budget: z.object({ chargedBytes: z.number().int().nonnegative(), chargedMs: z.number().int().nonnegative(), conservativeReservation: z.boolean() }).strict(), finishedAt: isoDateTimeSchema.nullable(), nextEligibleAt: isoDateTimeSchema.nullable() }).strict();
+export function tenantWebCrawlStatus(job, head) { return tenantWebCrawlStatusSchema.parse({ requestId: job.intent.requestId, jobRef: job.intent.jobRef, specRevision: job.intent.specRevision, state: head.state, phase: 'STATIC_ACQUISITION', requirementsState: 'DECLARED_NOT_EVALUATED', indexState: 'NOT_EVALUATED', coverage: { total: head.state === 'COMPLETE' ? head.queued : null, discovered: head.queued, acquired: head.acquired, registered: head.registered, pending: head.queued - head.cursor, gaps: head.gaps }, budget: { chargedBytes: head.chargedBytes, chargedMs: head.chargedMs, conservativeReservation: head.reservation !== null }, finishedAt: head.finishedAt, nextEligibleAt: head.notBefore }); }
+export function tenantWebPathMatches(pattern, pathname) { return pattern.endsWith('/**') ? (pathname === pattern.slice(0, -3) || pathname.startsWith(pattern.slice(0, -2))) : pathname === pattern; }
+export function tenantWebInScope(spec, raw, options = {}) {
+    const parsed = tenantWebUrlSchema.safeParse(raw);
+    if (!parsed.success)
+        return false;
+    const url = new URL(parsed.data), scope = spec.scope;
+    if (!scope.allowedOrigins.includes(url.origin))
+        return false;
+    if (options.robots)
+        return url.pathname === '/robots.txt' && !url.search;
+    let pathname;
+    try {
+        pathname = decodeURIComponent(url.pathname);
+    }
+    catch {
+        return false;
+    }
+    if (/[\\\x00-\x1f]/.test(pathname) || /%[0-9a-f]{2}/i.test(pathname))
+        return false;
+    // GitLab and similar public APIs encode a slash inside an identifier. Only an exact
+    // caller-listed URL without path filters can use it; section/prefix matching stays closed.
+    if (/%2f/i.test(url.pathname) && (!['SINGLE_PAGE', 'URL_LIST'].includes(scope.mode) || scope.includePaths.length > 0 || scope.excludePaths.length > 0))
+        return false;
+    if (scope.excludePaths.some(p => tenantWebPathMatches(p, pathname)))
+        return false;
+    if (options.bootstrap && raw === spec.url && ['SITEMAP', 'FEED'].includes(scope.mode))
+        return true;
+    if (scope.includePaths.length && !scope.includePaths.some(p => tenantWebPathMatches(p, pathname)))
+        return false;
+    if (scope.mode === 'SINGLE_PAGE')
+        return raw === spec.url;
+    if (scope.mode === 'URL_LIST')
+        return raw === spec.url || scope.urls.includes(raw);
+    return true;
+}
+export function sameTenantWebDelegation(a, b) { return a.intent.tenantId === b.intent.tenantId && tenantWebCanonical(a.policy) === tenantWebCanonical(b.policy) && tenantWebCanonical(a.intent.authority) === tenantWebCanonical(b.intent.authority) && tenantWebCanonical(a.intent.actor) === tenantWebCanonical(b.intent.actor); }

package/dist/internal/contracts/tenant-web-dynamic.js

@@ -0,0 +1,68 @@
+/** S3 opt-in contracts. Frozen Provider21/22 objects are never silently upgraded. */
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { tenantWebSpecSchema, tenantWebIntentSchema, tenantWebCanonical, tenantWebJobRef, tenantWebUrlSchema } from './tenant-web-collection.js';
+import { tenantWebPolicySchema, tenantWebTargetSchema, tenantWebOutcomeSchema, tenantWebHeadSchema, tenantWebChildOwnerSchema, tenantWebCrawlStatusSchema, tenantWebInScope } from './tenant-web-crawl.js';
+import { parseTenantResourceRef, tenantStorageKey, tenantResourceRefs } from './resource-scope.js';
+import { isoDateTimeSchema, sha256Schema } from './common.js';
+export const TENANT_WEB_DYNAMIC_CAPABILITY = 'TENANT_WEB_DYNAMIC_V1';
+const selector = z.string().trim().min(1).max(512).refine(s => !s.includes('\0'));
+const origin = tenantWebUrlSchema.refine(s => new URL(s).origin === s);
+export const tenantWebRenderSchema = z.object({
+    mode: z.enum(['HTTP_ONLY', 'AUTO', 'ALWAYS']).default('HTTP_ONLY'),
+    requiredSelector: selector.nullable().default(null), minTextChars: z.number().int().min(0).max(100000).default(80),
+    resourceOrigins: z.array(origin).max(16).default([]),
+    interaction: z.object({ kind: z.enum(['NONE', 'NEXT_PAGE', 'LOAD_MORE', 'SCROLL']), selector: selector.nullable().default(null), endSelector: selector.nullable().default(null), maxSteps: z.number().int().min(0).max(100).default(0) }).strict().default({ kind: 'NONE', selector: null, endSelector: null, maxSteps: 0 }),
+}).strict().superRefine((v, c) => {
+    if (v.interaction.kind !== 'NONE' && (v.mode === 'HTTP_ONLY' || v.interaction.maxSteps === 0))
+        c.addIssue({ code: 'custom', message: 'Interactions require a browser and a positive step bound' });
+    if (['NEXT_PAGE', 'LOAD_MORE'].includes(v.interaction.kind) && !v.interaction.selector)
+        c.addIssue({ code: 'custom', message: 'Button interactions require a selector' });
+    if (v.interaction.kind === 'NONE' && v.interaction.maxSteps !== 0)
+        c.addIssue({ code: 'custom', message: 'NONE cannot request actions' });
+    if (new Set(v.resourceOrigins).size !== v.resourceOrigins.length)
+        c.addIssue({ code: 'custom', message: 'Resource origins must be unique' });
+});
+export const tenantWebDynamicSpecSchema = z.object({ ...tenantWebSpecSchema.shape, schemaVersion: z.literal(2), render: tenantWebRenderSchema.default({ mode: 'HTTP_ONLY', requiredSelector: null, minTextChars: 80, resourceOrigins: [], interaction: { kind: 'NONE', selector: null, endSelector: null, maxSteps: 0 } }) }).strict().superRefine((v, c) => {
+    const { render: ignored, ...base } = v;
+    const old = tenantWebSpecSchema.safeParse({ ...base, schemaVersion: 1 });
+    if (!old.success)
+        for (const issue of old.error.issues)
+            c.addIssue({ ...issue, path: issue.path });
+    if (v.render.interaction.maxSteps > v.limits.maxInteractions)
+        c.addIssue({ code: 'custom', message: 'Page actions exceed the job interaction budget' });
+    if (v.render.interaction.kind === 'NEXT_PAGE' && !v.scope.followPagination)
+        c.addIssue({ code: 'custom', message: 'NEXT_PAGE requires pagination scope' });
+});
+export const tenantWebDynamicSpecRevision = (v) => 'sha256:' + createHash('sha256').update(tenantWebCanonical(tenantWebDynamicSpecSchema.parse(v))).digest('hex');
+export const tenantWebDynamicIntentSchema = z.object({ ...tenantWebIntentSchema.shape, schemaVersion: z.literal(2), requestedSpec: tenantWebDynamicSpecSchema, spec: tenantWebDynamicSpecSchema }).strict().superRefine((v, c) => {
+    if (v.actor.tenantId !== v.tenantId || v.jobRef !== tenantWebJobRef(v.tenantId, v.requestId) || v.specRevision !== tenantWebDynamicSpecRevision(v.spec) || v.inputRevision !== tenantWebDynamicSpecRevision(v.requestedSpec))
+        c.addIssue({ code: 'custom', message: 'Frozen Tenant intent identity mismatch' });
+    if (v.spec.limits.maxResourceBytes > Math.min(v.requestedSpec.limits.maxResourceBytes, v.requestedSpec.limits.maxTotalBytes) || tenantWebCanonical({ ...v.spec, limits: { ...v.spec.limits, maxResourceBytes: v.requestedSpec.limits.maxResourceBytes } }) !== tenantWebCanonical(v.requestedSpec))
+        c.addIssue({ code: 'custom', message: 'Only resource limit narrowing is permitted' });
+});
+export const tenantWebDynamicJobSchema = z.object({ schemaVersion: z.literal(3), intent: tenantWebDynamicIntentSchema, policy: tenantWebPolicySchema }).strict();
+export const tenantWebDynamicTargetSchema = z.object({ ...tenantWebTargetSchema.shape, ordinal: z.number().int().min(0).max(10999), role: z.enum(['PAGE', 'SITEMAP', 'FEED', 'ATTACHMENT']), attachment: z.enum(['PDF', 'IMAGE', 'AUDIO', 'VIDEO', 'OTHER']).nullable().default(null) }).strict().refine(v => (v.role === 'ATTACHMENT') === (v.attachment !== null));
+export const tenantWebDynamicOutcomeSchema = z.object({ ...tenantWebOutcomeSchema.shape, ordinal: tenantWebDynamicTargetSchema.shape.ordinal }).strict().refine(v => !v.registered || v.capture !== null);
+const count = z.number().int().min(0).max(11000);
+export const tenantWebDynamicHeadSchema = z.object({ ...tenantWebHeadSchema.shape,
+    schemaVersion: z.literal(2), queued: count, cursor: count, acquired: count, registered: count,
+    phase: z.enum(['RENDER', 'LINKS', 'PDF']).default('RENDER'), renderIndex: z.number().int().min(0).max(101), linkState: z.number().int().min(-1).max(101),
+    browserPages: z.number().int().min(0).max(10000), pagesQueued: z.number().int().min(0).max(10000), filesQueued: z.number().int().min(0).max(1000), renderedStates: count, pdfExtracted: z.number().int().min(0).max(1000), interactions: z.number().int().min(0).max(1000),
+    reservation: z.object({ bytes: z.number().int().nonnegative(), ms: z.number().int().nonnegative(), interactions: z.number().int().min(0).max(1000) }).strict().nullable(),
+}).strict().refine(v => v.queued === v.pagesQueued + v.filesQueued && v.cursor <= v.queued && v.registered <= v.acquired && v.acquired <= v.queued && (['COMPLETE', 'PARTIAL'].includes(v.state) === (v.finishedAt !== null)) && (!v.reservation || v.state === 'RUNNING' && v.chargedBytes >= v.reservation.bytes && v.chargedMs >= v.reservation.ms && v.interactions >= v.reservation.interactions) && (!v.notBefore || v.state === 'RUNNING' && !v.reservation) && (v.state !== 'PARTIAL' || v.gaps.length > 0) && (v.state !== 'COMPLETE' || v.queued > 0 && v.cursor === v.queued && v.gaps.length === 0 && v.registered === v.queued && !v.reservation && !v.notBefore));
+export const tenantWebDynamicChildOwnerSchema = z.object({ ...tenantWebChildOwnerSchema.shape, schemaVersion: z.literal(2), ordinal: tenantWebDynamicTargetSchema.shape.ordinal }).strict();
+export const tenantWebDynamicStatusSchema = z.object({ ...tenantWebCrawlStatusSchema.shape, phase: z.literal('DYNAMIC_ACQUISITION'), ocr: z.object({ capability: z.literal('UNAVAILABLE'), budgetState: z.literal('NOT_CONFIGURED'), processedPages: z.literal(0) }).strict(), dynamic: z.object({ browserPages: z.number().int().nonnegative(), pagesQueued: z.number().int().nonnegative(), filesQueued: z.number().int().nonnegative(), renderedStates: z.number().int().nonnegative(), pdfExtracted: z.number().int().nonnegative(), interactions: z.number().int().nonnegative() }).strict() }).strict();
+export function tenantWebDynamicStatus(job, h) { return tenantWebDynamicStatusSchema.parse({ requestId: job.intent.requestId, jobRef: job.intent.jobRef, specRevision: job.intent.specRevision, state: h.state, phase: 'DYNAMIC_ACQUISITION', ocr: { capability: 'UNAVAILABLE', budgetState: 'NOT_CONFIGURED', processedPages: 0 }, requirementsState: 'DECLARED_NOT_EVALUATED', indexState: 'NOT_EVALUATED', coverage: { total: h.state === 'COMPLETE' ? h.queued : null, discovered: h.queued, acquired: h.acquired, registered: h.registered, pending: h.queued - h.cursor, gaps: h.gaps }, budget: { chargedBytes: h.chargedBytes, chargedMs: h.chargedMs, conservativeReservation: h.reservation !== null }, dynamic: { browserPages: h.browserPages, pagesQueued: h.pagesQueued, filesQueued: h.filesQueued, renderedStates: h.renderedStates, pdfExtracted: h.pdfExtracted, interactions: h.interactions }, finishedAt: h.finishedAt, nextEligibleAt: h.notBefore }); }
+export function tenantWebAttachmentInScope(spec, url, robots = false) { return tenantWebInScope({ url: spec.url, scope: { ...spec.scope, mode: 'SITE_SECTION' } }, url, { robots }); }
+/** Browser records refer to retained immutable evidence, never inline runtime bodies. */
+export const tenantWebBrowserResponseSchema = z.object({ url: tenantWebUrlSchema, finalUrl: tenantWebUrlSchema, status: z.number().int().min(200).max(299), headers: z.record(z.string(), z.string().max(8192)), ref: z.string().min(1).max(1024), hash: sha256Schema, observedAt: isoDateTimeSchema }).strict();
+export const tenantWebBrowserStateSchema = z.object({ schemaVersion: z.literal(1), ordinal: tenantWebDynamicTargetSchema.shape.ordinal, index: z.number().int().min(0).max(100), url: tenantWebUrlSchema, domRef: z.string().min(1).max(1024), domHash: sha256Schema, visibleRef: z.string().min(1).max(1024).optional(), visibleHash: sha256Schema.optional(), observedAt: isoDateTimeSchema, responseCount: z.number().int().min(0).max(64), navigationCount: z.number().int().min(0).max(64), actions: z.number().int().min(0).max(1000), done: z.boolean(), gap: z.string().regex(/^[A-Z][A-Z0-9_]{0,127}$/).nullable(), interactionRef: z.string().min(1).max(1024) }).strict();
+export function tenantWebPartIdentity(tenantId, parentRef, part) {
+    const parent = parseTenantResourceRef(parentRef);
+    if (!part || part.length > 256 || !parent || parent.storageKey !== tenantStorageKey(tenantId) || parent.resourceType !== 'evidence')
+        throw new Error('TENANT_WEB_PART_IDENTITY');
+    const resourceId = 'web_' + createHash('sha256').update(tenantWebCanonical(['TENANT_WEB_PART_V1', tenantId, parentRef, part])).digest('hex');
+    return { resourceId, version: 1, ...tenantResourceRefs({ tenantId, resourceType: 'evidence', resourceId, version: 1 }) };
+}
+export const tenantWebBrowserCapabilitySchema = z.object({ executablePath: z.string().min(1).max(4096).refine(s => s.startsWith('/') && !s.includes('\0')), navigationTimeoutMs: z.number().int().min(1000).max(30000).default(15000), settleMs: z.number().int().min(100).max(3000).default(300), maxRequests: z.number().int().min(1).max(64).default(32), captureVisible: z.boolean().optional() }).strict();

package/dist/internal/contracts/tenant-web-results.js

@@ -0,0 +1,41 @@
+/** 结果与覆盖独立于意图受理；仅有原件/字段出处才允许声明满足要求。 */
+import { z } from 'zod';
+import { isoDateTimeSchema, sha256Schema } from './common.js';
+import { tenantResourceRefSchema, parseTenantResourceRef } from './resource-scope.js';
+import { tenantWebJobRefSchema, tenantWebUrlSchema } from './tenant-web-collection.js';
+const count = z.number().int().nonnegative().safe();
+export const tenantWebFieldResultSchema = z.object({
+    name: z.string().min(1).max(64), state: z.enum(['PRESENT', 'MISSING', 'UNSUPPORTED']), value: z.json().nullable(),
+    citations: z.array(z.object({ evidenceRef: tenantResourceRefSchema, contentHash: sha256Schema, locator: z.string().min(1).max(2048), excerpt: z.string().min(1).max(4000) }).strict()).max(16),
+    reason: z.string().regex(/^[A-Z][A-Z0-9_]{0,127}$/).nullable(),
+}).strict().superRefine((v, ctx) => {
+    if (v.state === 'PRESENT' ? (v.value === null || v.citations.length === 0 || v.reason !== null) : (v.value !== null || v.reason === null))
+        ctx.addIssue({ code: 'custom', message: 'Present values require citations; gaps require a reason without an invented value' });
+    if (v.citations.some(c => parseTenantResourceRef(c.evidenceRef)?.resourceType !== 'evidence'))
+        ctx.addIssue({ code: 'custom', message: 'Citations require actual Evidence identities' });
+});
+export const tenantWebResultSchema = z.object({
+    schemaVersion: z.literal(1), jobRef: tenantWebJobRefSchema, evidenceRef: tenantResourceRefSchema,
+    sourceUrl: tenantWebUrlSchema, contentHash: sha256Schema, observedAt: isoDateTimeSchema,
+    documentRef: tenantResourceRefSchema.nullable(), fields: z.array(tenantWebFieldResultSchema).max(64),
+}).strict().superRefine((v, ctx) => {
+    const key = new URL(v.jobRef).hostname, mine = (ref) => parseTenantResourceRef(ref)?.storageKey === key;
+    if (!mine(v.evidenceRef) || parseTenantResourceRef(v.evidenceRef)?.resourceType !== 'evidence' || v.documentRef && (!mine(v.documentRef) || parseTenantResourceRef(v.documentRef)?.resourceType !== 'source_document') || v.fields.some(f => f.citations.some(c => !mine(c.evidenceRef))))
+        ctx.addIssue({ code: 'custom', message: 'Results and their typed evidence/document must retain the owning Tenant' });
+});
+export const tenantWebCoverageSchema = z.object({
+    schemaVersion: z.literal(1), jobRef: tenantWebJobRefSchema, scopeRevision: sha256Schema,
+    state: z.enum(['NOT_STARTED', 'PARTIAL', 'COMPLETE', 'UNKNOWN']), total: count.nullable(),
+    discovered: count, acquired: count, extracted: count, registered: count, pending: count,
+    frontierExhausted: z.boolean(), limitReached: z.boolean(),
+    gaps: z.array(z.object({ code: z.string().regex(/^[A-Z][A-Z0-9_]{0,127}$/), url: tenantWebUrlSchema.nullable() }).strict()).max(100),
+}).strict().superRefine((v, ctx) => {
+    if (v.state === 'COMPLETE' && (!v.frontierExhausted || v.pending !== 0 || v.limitReached || v.gaps.length > 0))
+        ctx.addIssue({ code: 'custom', message: 'A truncated, pending or incomplete scope cannot be complete' });
+    if (v.state === 'COMPLETE' && (v.total !== v.discovered || v.acquired !== v.discovered || v.registered !== v.acquired))
+        ctx.addIssue({ code: 'custom', message: 'Completion requires a known exhausted target count and all originals registered' });
+    if (v.state === 'NOT_STARTED' && (v.discovered !== 0 || v.acquired !== 0 || v.extracted !== 0 || v.registered !== 0 || v.pending !== 0))
+        ctx.addIssue({ code: 'custom', message: 'Not-started coverage cannot carry completed work' });
+    if (v.acquired > v.discovered || v.extracted > v.acquired || v.registered > v.acquired || v.pending > v.discovered || v.total !== null && v.total < v.discovered)
+        ctx.addIssue({ code: 'custom', message: 'Coverage counters must describe actual bounded work' });
+});

package/dist/internal/contracts/tenant-web-workflow.js

@@ -0,0 +1,29 @@
+/** S5 operational state; acquisition/content evidence and business review remain separate. */
+import { z } from 'zod';
+import { tenantWebContentJobSchema } from './tenant-web-content.js';
+import { tenantWebJobRefSchema, tenantWebCanonical } from './tenant-web-collection.js';
+import { tenantCollectionCycleSchema } from './tenant-collection.js';
+import { isoDateTimeSchema } from './common.js';
+export const TENANT_WEB_WORKFLOW_CAPABILITY = 'TENANT_WEB_WORKFLOW_V1';
+export const tenantWebScheduleSchema = z.discriminatedUnion('mode', [z.object({ mode: z.literal('ONCE') }).strict(), z.object({ mode: z.literal('PERIODIC'), intervalSeconds: z.number().int().min(60).max(2592000) }).strict()]);
+export const tenantWebWorkflowJobSchema = z.object({ ...tenantWebContentJobSchema.shape, schemaVersion: z.literal(5), schedule: tenantWebScheduleSchema, cycle: z.object({ kind: z.enum(['INITIAL', 'MANUAL_REFRESH', 'DUE']), rootJobRef: tenantWebJobRefSchema, previousJobRef: tenantWebJobRefSchema.nullable(), ordinal: z.number().int().nonnegative().safe(), requestedEpoch: z.number().int().nonnegative().safe() }).strict() }).strict().superRefine((v, c) => {
+    const old = tenantWebContentJobSchema.safeParse({ schemaVersion: 4, intent: v.intent, policy: v.policy, contentPlan: v.contentPlan, contentRevision: v.contentRevision, retainedFrom: v.retainedFrom });
+    if (!old.success)
+        c.addIssue({ code: 'custom', message: 'Invalid frozen content intent' });
+    const wrongTenant = [v.cycle.rootJobRef, v.cycle.previousJobRef].some(ref => ref && new URL(ref).hostname !== new URL(v.intent.jobRef).hostname), wrongCycle = v.cycle.kind === 'INITIAL' ? (v.cycle.rootJobRef !== v.intent.jobRef || v.cycle.previousJobRef !== null || v.cycle.ordinal !== 0 || v.cycle.requestedEpoch !== 0) : (v.cycle.rootJobRef === v.intent.jobRef || v.cycle.previousJobRef === null || v.cycle.ordinal < 1 || v.retainedFrom !== null);
+    if (wrongTenant || wrongCycle)
+        c.addIssue({ code: 'custom', message: 'Cycle must retain its exact Tenant/root/previous identity' });
+    if (v.retainedFrom && v.schedule.mode !== 'ONCE')
+        c.addIssue({ code: 'custom', message: 'Retained derivation cannot enable periodic source observations' });
+});
+export function tenantWebExecutableContent(job) { return tenantWebContentJobSchema.parse({ schemaVersion: 4, intent: job.intent, policy: job.policy, contentPlan: job.contentPlan, contentRevision: job.contentRevision, retainedFrom: job.retainedFrom }); }
+export const tenantWebLifecycleSchema = z.object({ schemaVersion: z.literal(1), seq: z.number().int().nonnegative().safe(), epoch: z.number().int().nonnegative().safe(), state: z.enum(['ACTIVE', 'PAUSED', 'CANCELLED']), currentJobRef: tenantWebJobRefSchema, cycleOrdinal: z.number().int().nonnegative().safe(), lastObservedAt: isoDateTimeSchema.nullable(), updatedAt: isoDateTimeSchema }).strict().refine(v => v.epoch <= v.seq && v.cycleOrdinal <= v.seq);
+export const tenantWebControlInputSchema = z.object({ jobRef: tenantWebJobRefSchema, requestId: tenantCollectionCycleSchema, expectedEpoch: z.number().int().nonnegative().safe(), action: z.enum(['PAUSE', 'RESUME', 'CANCEL']) }).strict();
+export const tenantWebControlOperationSchema = z.object({ ...tenantWebControlInputSchema.shape, actor: tenantWebWorkflowJobSchema.shape.intent.shape.actor, authority: tenantWebWorkflowJobSchema.shape.intent.shape.authority }).strict();
+export const tenantWebLifecycleReceiptSchema = z.object({ operation: tenantWebControlOperationSchema, committed: tenantWebLifecycleSchema }).strict();
+export const tenantWebWorkflowStatusSchema = z.object({ jobRef: tenantWebJobRefSchema, requestId: tenantCollectionCycleSchema, rootJobRef: tenantWebJobRefSchema, executionJobRef: tenantWebJobRefSchema, state: z.enum(['QUEUED', 'RUNNING', 'COMPLETE', 'PARTIAL', 'PAUSED', 'CANCELLED']), control: tenantWebLifecycleSchema, cycle: tenantWebWorkflowJobSchema.shape.cycle, schedule: tenantWebScheduleSchema, nextDueAt: isoDateTimeSchema.nullable(), stages: z.object({ intent: z.literal('PERSISTED'), acquisition: z.object({ state: z.enum(['QUEUED', 'RUNNING', 'COMPLETE', 'PARTIAL']), discovered: z.number().int().nonnegative(), acquired: z.number().int().nonnegative(), registered: z.number().int().nonnegative(), pending: z.number().int().nonnegative(), gaps: z.array(z.string()).max(32) }).strict(), content: z.object({ state: z.enum(['PENDING', 'SATISFIED', 'PARTIAL']), processed: z.number().int().nonnegative(), registered: z.number().int().nonnegative(), gaps: z.array(z.string()).max(32) }).strict(), index: z.literal('NOT_PROVEN_QUERY_TENANT_INDEX_STATUS'), readability: z.literal('NOT_PROVEN_UNTIL_ACTUAL_READ'), review: z.literal('UNREVIEWED') }).strict(), budget: z.object({ chargedBytes: z.number().int().nonnegative(), chargedMs: z.number().int().nonnegative(), conservativeReservation: z.boolean() }).strict() }).strict().superRefine((v, c) => { const key = new URL(v.jobRef).hostname; if ([v.rootJobRef, v.executionJobRef, v.control.currentJobRef, v.cycle.rootJobRef].some(ref => new URL(ref).hostname !== key))
+    c.addIssue({ code: 'custom', message: 'Exact Tenant workflow required' }); });
+export function tenantWebNextDue(root, head, current) { if (root.schedule.mode !== 'PERIODIC' || head.state !== 'ACTIVE')
+    return null; return new Date(Math.max(Date.parse(head.lastObservedAt ?? current.intent.submittedAt), Date.parse(current.intent.submittedAt)) + root.schedule.intervalSeconds * 1000).toISOString(); }
+export const sameTenantWebWorkflow = (a, b) => tenantWebCanonical(a.intent.actor) === tenantWebCanonical(b.intent.actor) && tenantWebCanonical(a.intent.authority) === tenantWebCanonical(b.intent.authority) && tenantWebCanonical(a.policy) === tenantWebCanonical(b.policy) && a.intent.tenantId === b.intent.tenantId && a.intent.specRevision === b.intent.specRevision && a.contentRevision === b.contentRevision && tenantWebCanonical(a.schedule) === tenantWebCanonical(b.schedule);
+export const tenantWebLifecycleEventSchema = z.object({ before: tenantWebLifecycleSchema, after: tenantWebLifecycleSchema, operation: tenantWebControlOperationSchema.nullable() }).strict().refine(v => v.after.seq === v.before.seq + 1 && v.after.epoch === v.before.epoch + (v.operation ? 1 : 0) && (!v.before.lastObservedAt || v.after.lastObservedAt !== null && v.after.lastObservedAt >= v.before.lastObservedAt) && v.after.cycleOrdinal >= v.before.cycleOrdinal && v.after.cycleOrdinal <= v.before.cycleOrdinal + 1 && (v.operation !== null || v.after.state === v.before.state) && (!v.operation || v.operation.expectedEpoch === v.before.epoch && v.after.cycleOrdinal === v.before.cycleOrdinal && v.after.currentJobRef === v.before.currentJobRef && v.after.state === (v.operation.action === 'PAUSE' ? 'PAUSED' : v.operation.action === 'RESUME' ? 'ACTIVE' : 'CANCELLED')) && (v.before.state !== 'CANCELLED' || v.after.state === 'CANCELLED') && (v.after.cycleOrdinal !== v.before.cycleOrdinal ? v.before.state === 'ACTIVE' && v.after.state === 'ACTIVE' && v.after.currentJobRef !== v.before.currentJobRef : v.after.currentJobRef === v.before.currentJobRef));