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

package/dist/internal/contracts/tenant-web-content.d.ts

@@ -0,0 +1,383 @@
+/** S4 composes frozen S3 acquisition with a separately versioned derived plan. */
+import { z } from 'zod';
+import { type TenantWebDynamicHead } from './tenant-web-dynamic.js';
+export declare const tenantWebContentJobSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<4>;
+    contentPlan: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        compiler: z.ZodEnum<{
+            CALLER_PLAN_V1: "CALLER_PLAN_V1";
+            BOUNDED_LANGUAGE_V1: "BOUNDED_LANGUAGE_V1";
+        }>;
+        extractor: z.ZodObject<{
+            id: z.ZodLiteral<"native-knowledge.web-content">;
+            version: z.ZodLiteral<"1.0.0">;
+        }, z.core.$strict>;
+        body: z.ZodBoolean;
+        tables: z.ZodBoolean;
+        links: z.ZodBoolean;
+        recordSelector: z.ZodNullable<z.ZodString>;
+        fields: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            selector: z.ZodString;
+            value: z.ZodDefault<z.ZodEnum<{
+                TEXT: "TEXT";
+                JSON: "JSON";
+                ATTRIBUTE: "ATTRIBUTE";
+            }>>;
+            attribute: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+                datetime: "datetime";
+                value: "value";
+                title: "title";
+                href: "href";
+                alt: "alt";
+                content: "content";
+                src: "src";
+            }>>>;
+            type: z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+                object: "object";
+                array: "array";
+            }>;
+            required: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        maxRecords: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>;
+    contentRevision: z.ZodString;
+    retainedFrom: z.ZodNullable<z.ZodString>;
+    intent: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<2>;
+        requestedSpec: z.ZodObject<{
+            schemaVersion: z.ZodLiteral<2>;
+            render: z.ZodDefault<z.ZodObject<{
+                mode: z.ZodDefault<z.ZodEnum<{
+                    HTTP_ONLY: "HTTP_ONLY";
+                    AUTO: "AUTO";
+                    ALWAYS: "ALWAYS";
+                }>>;
+                requiredSelector: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                minTextChars: z.ZodDefault<z.ZodNumber>;
+                resourceOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                interaction: z.ZodDefault<z.ZodObject<{
+                    kind: z.ZodEnum<{
+                        NONE: "NONE";
+                        NEXT_PAGE: "NEXT_PAGE";
+                        LOAD_MORE: "LOAD_MORE";
+                        SCROLL: "SCROLL";
+                    }>;
+                    selector: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                    endSelector: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                    maxSteps: z.ZodDefault<z.ZodNumber>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+            url: z.ZodString;
+            scope: z.ZodObject<{
+                mode: z.ZodEnum<{
+                    FEED: "FEED";
+                    SINGLE_PAGE: "SINGLE_PAGE";
+                    URL_LIST: "URL_LIST";
+                    SITE_SECTION: "SITE_SECTION";
+                    SITEMAP: "SITEMAP";
+                }>;
+                allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                includePaths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                excludePaths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                urls: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                followPagination: z.ZodDefault<z.ZodBoolean>;
+                followDetailLinks: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strict>;
+            requirements: z.ZodObject<{
+                instruction: z.ZodString;
+                fields: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    type: z.ZodEnum<{
+                        string: "string";
+                        number: "number";
+                        boolean: "boolean";
+                        object: "object";
+                        array: "array";
+                    }>;
+                    required: z.ZodDefault<z.ZodBoolean>;
+                }, z.core.$strict>>>;
+                outputs: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                    RAW: "RAW";
+                    DOCUMENT: "DOCUMENT";
+                    RECORDS: "RECORDS";
+                }>>>;
+                attachments: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                    PDF: "PDF";
+                    IMAGE: "IMAGE";
+                    AUDIO: "AUDIO";
+                    VIDEO: "VIDEO";
+                    OTHER: "OTHER";
+                }>>>;
+            }, z.core.$strict>;
+            limits: z.ZodDefault<z.ZodObject<{
+                maxPages: z.ZodDefault<z.ZodNumber>;
+                maxDepth: z.ZodDefault<z.ZodNumber>;
+                maxResourceBytes: z.ZodDefault<z.ZodNumber>;
+                maxTotalBytes: z.ZodDefault<z.ZodNumber>;
+                maxRuntimeMs: z.ZodDefault<z.ZodNumber>;
+                maxInteractions: z.ZodDefault<z.ZodNumber>;
+                maxFiles: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strict>>;
+            refresh: z.ZodDefault<z.ZodObject<{
+                mode: z.ZodLiteral<"ONCE">;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        spec: z.ZodObject<{
+            schemaVersion: z.ZodLiteral<2>;
+            render: z.ZodDefault<z.ZodObject<{
+                mode: z.ZodDefault<z.ZodEnum<{
+                    HTTP_ONLY: "HTTP_ONLY";
+                    AUTO: "AUTO";
+                    ALWAYS: "ALWAYS";
+                }>>;
+                requiredSelector: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                minTextChars: z.ZodDefault<z.ZodNumber>;
+                resourceOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                interaction: z.ZodDefault<z.ZodObject<{
+                    kind: z.ZodEnum<{
+                        NONE: "NONE";
+                        NEXT_PAGE: "NEXT_PAGE";
+                        LOAD_MORE: "LOAD_MORE";
+                        SCROLL: "SCROLL";
+                    }>;
+                    selector: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                    endSelector: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                    maxSteps: z.ZodDefault<z.ZodNumber>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+            url: z.ZodString;
+            scope: z.ZodObject<{
+                mode: z.ZodEnum<{
+                    FEED: "FEED";
+                    SINGLE_PAGE: "SINGLE_PAGE";
+                    URL_LIST: "URL_LIST";
+                    SITE_SECTION: "SITE_SECTION";
+                    SITEMAP: "SITEMAP";
+                }>;
+                allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                includePaths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                excludePaths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                urls: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                followPagination: z.ZodDefault<z.ZodBoolean>;
+                followDetailLinks: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strict>;
+            requirements: z.ZodObject<{
+                instruction: z.ZodString;
+                fields: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    type: z.ZodEnum<{
+                        string: "string";
+                        number: "number";
+                        boolean: "boolean";
+                        object: "object";
+                        array: "array";
+                    }>;
+                    required: z.ZodDefault<z.ZodBoolean>;
+                }, z.core.$strict>>>;
+                outputs: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                    RAW: "RAW";
+                    DOCUMENT: "DOCUMENT";
+                    RECORDS: "RECORDS";
+                }>>>;
+                attachments: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                    PDF: "PDF";
+                    IMAGE: "IMAGE";
+                    AUDIO: "AUDIO";
+                    VIDEO: "VIDEO";
+                    OTHER: "OTHER";
+                }>>>;
+            }, z.core.$strict>;
+            limits: z.ZodDefault<z.ZodObject<{
+                maxPages: z.ZodDefault<z.ZodNumber>;
+                maxDepth: z.ZodDefault<z.ZodNumber>;
+                maxResourceBytes: z.ZodDefault<z.ZodNumber>;
+                maxTotalBytes: z.ZodDefault<z.ZodNumber>;
+                maxRuntimeMs: z.ZodDefault<z.ZodNumber>;
+                maxInteractions: z.ZodDefault<z.ZodNumber>;
+                maxFiles: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strict>>;
+            refresh: z.ZodDefault<z.ZodObject<{
+                mode: z.ZodLiteral<"ONCE">;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        tenantId: z.ZodString;
+        requestId: z.ZodString;
+        jobRef: z.ZodString;
+        inputRevision: z.ZodString;
+        specRevision: z.ZodString;
+        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">;
+        submittedAt: z.ZodISODateTime;
+    }, z.core.$strict>;
+    policy: 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>;
+}, z.core.$strict>;
+export type TenantWebContentJob = z.infer<typeof tenantWebContentJobSchema>;
+export declare const tenantWebContentHeadSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    seq: z.ZodNumber;
+    cursor: z.ZodNumber;
+    variant: z.ZodNumber;
+    processed: z.ZodNumber;
+    registered: z.ZodNumber;
+    missing: z.ZodNumber;
+    attempts: z.ZodNumber;
+    chargedBytes: z.ZodNumber;
+    chargedMs: z.ZodNumber;
+    reservation: z.ZodNullable<z.ZodObject<{
+        bytes: z.ZodNumber;
+        ms: z.ZodNumber;
+    }, z.core.$strict>>;
+    state: z.ZodEnum<{
+        PARTIAL: "PARTIAL";
+        COMPLETE: "COMPLETE";
+        QUEUED: "QUEUED";
+        RUNNING: "RUNNING";
+    }>;
+    gaps: z.ZodArray<z.ZodString>;
+    finishedAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type TenantWebContentHead = z.infer<typeof tenantWebContentHeadSchema>;
+export declare const tenantWebContentOutcomeSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    index: z.ZodNumber;
+    ordinal: z.ZodNumber;
+    variant: z.ZodNumber;
+    documentRef: z.ZodNullable<z.ZodString>;
+    gaps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const tenantWebContentStatusSchema: z.ZodObject<{
+    phase: z.ZodEnum<{
+        DYNAMIC_ACQUISITION: "DYNAMIC_ACQUISITION";
+        CONTENT_DERIVATION: "CONTENT_DERIVATION";
+    }>;
+    requirementsState: z.ZodEnum<{
+        PENDING: "PENDING";
+        PARTIAL: "PARTIAL";
+        SATISFIED: "SATISFIED";
+    }>;
+    contentRevision: z.ZodString;
+    content: z.ZodObject<{
+        processed: z.ZodNumber;
+        registered: z.ZodNumber;
+        missing: z.ZodNumber;
+        gaps: z.ZodArray<z.ZodString>;
+        compiler: z.ZodEnum<{
+            CALLER_PLAN_V1: "CALLER_PLAN_V1";
+            BOUNDED_LANGUAGE_V1: "BOUNDED_LANGUAGE_V1";
+        }>;
+        model: z.ZodLiteral<"DISABLED_NO_MODEL_CALLS">;
+    }, z.core.$strict>;
+    ocr: z.ZodObject<{
+        capability: z.ZodLiteral<"UNAVAILABLE">;
+        budgetState: z.ZodLiteral<"NOT_CONFIGURED">;
+        processedPages: z.ZodLiteral<0>;
+    }, z.core.$strict>;
+    dynamic: z.ZodObject<{
+        browserPages: z.ZodNumber;
+        pagesQueued: z.ZodNumber;
+        filesQueued: z.ZodNumber;
+        renderedStates: z.ZodNumber;
+        pdfExtracted: z.ZodNumber;
+        interactions: z.ZodNumber;
+    }, z.core.$strict>;
+    requestId: z.ZodString;
+    jobRef: z.ZodString;
+    specRevision: z.ZodString;
+    state: z.ZodEnum<{
+        PARTIAL: "PARTIAL";
+        COMPLETE: "COMPLETE";
+        QUEUED: "QUEUED";
+        RUNNING: "RUNNING";
+    }>;
+    indexState: z.ZodLiteral<"NOT_EVALUATED">;
+    coverage: z.ZodObject<{
+        total: z.ZodNullable<z.ZodNumber>;
+        discovered: z.ZodNumber;
+        acquired: z.ZodNumber;
+        registered: z.ZodNumber;
+        pending: z.ZodNumber;
+        gaps: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    budget: z.ZodObject<{
+        chargedBytes: z.ZodNumber;
+        chargedMs: z.ZodNumber;
+        conservativeReservation: z.ZodBoolean;
+    }, z.core.$strict>;
+    finishedAt: z.ZodNullable<z.ZodISODateTime>;
+    nextEligibleAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+export declare function tenantWebContentStatus(job: TenantWebContentJob, a: TenantWebDynamicHead, h: TenantWebContentHead): {
+    phase: "DYNAMIC_ACQUISITION" | "CONTENT_DERIVATION";
+    requirementsState: "PENDING" | "PARTIAL" | "SATISFIED";
+    contentRevision: string;
+    content: {
+        processed: number;
+        registered: number;
+        missing: number;
+        gaps: string[];
+        compiler: "CALLER_PLAN_V1" | "BOUNDED_LANGUAGE_V1";
+        model: "DISABLED_NO_MODEL_CALLS";
+    };
+    ocr: {
+        capability: "UNAVAILABLE";
+        budgetState: "NOT_CONFIGURED";
+        processedPages: 0;
+    };
+    dynamic: {
+        browserPages: number;
+        pagesQueued: number;
+        filesQueued: number;
+        renderedStates: number;
+        pdfExtracted: number;
+        interactions: number;
+    };
+    requestId: string;
+    jobRef: string;
+    specRevision: string;
+    state: "PARTIAL" | "COMPLETE" | "QUEUED" | "RUNNING";
+    indexState: "NOT_EVALUATED";
+    coverage: {
+        total: number | null;
+        discovered: number;
+        acquired: number;
+        registered: number;
+        pending: number;
+        gaps: string[];
+    };
+    budget: {
+        chargedBytes: number;
+        chargedMs: number;
+        conservativeReservation: boolean;
+    };
+    finishedAt: string | null;
+    nextEligibleAt: string | null;
+};

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 }); }