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

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

@@ -0,0 +1,66 @@
+/** 结果与覆盖独立于意图受理；仅有原件/字段出处才允许声明满足要求。 */
+import { z } from 'zod';
+export declare const tenantWebFieldResultSchema: z.ZodObject<{
+    name: z.ZodString;
+    state: z.ZodEnum<{
+        MISSING: "MISSING";
+        UNSUPPORTED: "UNSUPPORTED";
+        PRESENT: "PRESENT";
+    }>;
+    value: z.ZodNullable<z.ZodJSONSchema>;
+    citations: z.ZodArray<z.ZodObject<{
+        evidenceRef: z.ZodString;
+        contentHash: z.ZodString;
+        locator: z.ZodString;
+        excerpt: z.ZodString;
+    }, z.core.$strict>>;
+    reason: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const tenantWebResultSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    jobRef: z.ZodString;
+    evidenceRef: z.ZodString;
+    sourceUrl: z.ZodString;
+    contentHash: z.ZodString;
+    observedAt: z.ZodISODateTime;
+    documentRef: z.ZodNullable<z.ZodString>;
+    fields: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        state: z.ZodEnum<{
+            MISSING: "MISSING";
+            UNSUPPORTED: "UNSUPPORTED";
+            PRESENT: "PRESENT";
+        }>;
+        value: z.ZodNullable<z.ZodJSONSchema>;
+        citations: z.ZodArray<z.ZodObject<{
+            evidenceRef: z.ZodString;
+            contentHash: z.ZodString;
+            locator: z.ZodString;
+            excerpt: z.ZodString;
+        }, z.core.$strict>>;
+        reason: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const tenantWebCoverageSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    jobRef: z.ZodString;
+    scopeRevision: z.ZodString;
+    state: z.ZodEnum<{
+        UNKNOWN: "UNKNOWN";
+        PARTIAL: "PARTIAL";
+        COMPLETE: "COMPLETE";
+        NOT_STARTED: "NOT_STARTED";
+    }>;
+    total: z.ZodNullable<z.ZodNumber>;
+    discovered: z.ZodNumber;
+    acquired: z.ZodNumber;
+    extracted: z.ZodNumber;
+    registered: z.ZodNumber;
+    pending: z.ZodNumber;
+    frontierExhausted: z.ZodBoolean;
+    limitReached: z.ZodBoolean;
+    gaps: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        url: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$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' });
+});