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

package/dist/internal/contracts/collection.js

@@ -0,0 +1,174 @@
+import { z } from 'zod';
+import { idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema, } from './common.js';
+import { acquisitionTargetSchema, collectionRefreshSchema } from './project-intent.js';
+export const collectionBatchSourceBindingSchema = z.object({
+    sourceId: idSchema,
+    sourceRef: stableUriSchema,
+    sourceRevisionRef: stableUriSchema,
+    targetId: sha256Schema,
+}).strict();
+/** The collector-facing task deliberately contains no project/source-family semantics. */
+export const collectionTaskSchema = z.object({
+    taskId: idSchema,
+    targetId: sha256Schema,
+    target: acquisitionTargetSchema,
+}).strict();
+export const collectionBatchTriggerSchema = z.enum(['MANUAL', 'DUE']);
+export const collectionBatchSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    projectRef: stableUriSchema,
+    projectIntentRef: stableUriSchema,
+    requestId: idSchema,
+    batchId: idSchema,
+    batchRef: stableUriSchema,
+    trigger: collectionBatchTriggerSchema.default('MANUAL'),
+    createdAt: isoDateTimeSchema,
+    sourceBindings: z.array(collectionBatchSourceBindingSchema).min(1).max(10_000),
+    tasks: z.array(collectionTaskSchema).min(1).max(10_000),
+}).strict().superRefine((value, ctx) => {
+    const sourceIds = new Set(), bindingTargets = new Set(), taskIds = new Set(), taskTargets = new Set();
+    for (let i = 0; i < value.sourceBindings.length; i += 1) {
+        const row = value.sourceBindings[i];
+        if (sourceIds.has(row.sourceId))
+            ctx.addIssue({ code: 'custom', path: ['sourceBindings', i, 'sourceId'], message: 'sourceId must be unique in a batch' });
+        if (bindingTargets.has(row.targetId))
+            ctx.addIssue({ code: 'custom', path: ['sourceBindings', i, 'targetId'], message: 'targetId must be unique in project source bindings' });
+        sourceIds.add(row.sourceId);
+        bindingTargets.add(row.targetId);
+    }
+    for (let i = 0; i < value.tasks.length; i += 1) {
+        const row = value.tasks[i];
+        if (taskIds.has(row.taskId))
+            ctx.addIssue({ code: 'custom', path: ['tasks', i, 'taskId'], message: 'taskId must be unique in a batch' });
+        if (taskTargets.has(row.targetId))
+            ctx.addIssue({ code: 'custom', path: ['tasks', i, 'targetId'], message: 'targetId must be unique in a batch' });
+        taskIds.add(row.taskId);
+        taskTargets.add(row.targetId);
+    }
+    for (let i = 0; i < value.tasks.length; i += 1)
+        if (!bindingTargets.has(value.tasks[i].targetId))
+            ctx.addIssue({ code: 'custom', path: ['tasks', i, 'targetId'], message: 'task target must have a source binding' });
+    for (let i = 0; i < value.sourceBindings.length; i += 1)
+        if (!taskTargets.has(value.sourceBindings[i].targetId))
+            ctx.addIssue({ code: 'custom', path: ['sourceBindings', i, 'targetId'], message: 'source binding must have a collector task' });
+});
+export const collectorBatchViewSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    batchId: idSchema,
+    tasks: z.array(collectionTaskSchema).min(1).max(10_000),
+}).strict();
+export const sourceCollectionDueReasonSchema = z.enum([
+    'DISABLED',
+    'MANUAL',
+    'PENDING_BATCH',
+    'SPECIALIZED_EXECUTOR',
+    'SPECIALIZED_COLLECTOR',
+    'NEVER_ATTEMPTED',
+    'INTERVAL_WAIT',
+    'INTERVAL_ELAPSED',
+]);
+export const sourceCollectionDueEntrySchema = z.object({
+    sourceId: idSchema,
+    sourceRef: stableUriSchema,
+    sourceRevisionRef: stableUriSchema,
+    enabled: z.boolean(),
+    refresh: collectionRefreshSchema,
+    lastAttemptAt: isoDateTimeSchema.nullable(),
+    lastState: z.enum(['ACQUIRED', 'ACCESS_CONTROLLED', 'HTTP_TERMINAL', 'FAILED']).nullable(),
+    lastBatchRef: stableUriSchema.nullable(),
+    lastRunId: idSchema.nullable(),
+    pendingBatchRef: stableUriSchema.nullable(),
+    nextDueAt: isoDateTimeSchema.nullable(),
+    due: z.boolean(),
+    reason: sourceCollectionDueReasonSchema,
+}).strict().superRefine((value, ctx) => {
+    if (value.reason === 'PENDING_BATCH' && !value.pendingBatchRef)
+        ctx.addIssue({ code: 'custom', path: ['pendingBatchRef'], message: 'PENDING_BATCH requires pendingBatchRef' });
+    if (value.reason !== 'PENDING_BATCH' && value.pendingBatchRef)
+        ctx.addIssue({ code: 'custom', path: ['pendingBatchRef'], message: 'pendingBatchRef is only valid for PENDING_BATCH' });
+    if (value.due && !['NEVER_ATTEMPTED', 'INTERVAL_ELAPSED'].includes(value.reason))
+        ctx.addIssue({ code: 'custom', path: ['due'], message: 'due source must be never attempted or interval elapsed' });
+    if (value.refresh.mode === 'MANUAL' && value.nextDueAt !== null)
+        ctx.addIssue({ code: 'custom', path: ['nextDueAt'], message: 'MANUAL source has no automatic nextDueAt' });
+});
+export const projectCollectionDuePlanSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    projectRef: stableUriSchema,
+    projectIntentRef: stableUriSchema,
+    assessedAt: isoDateTimeSchema,
+    sourceCount: z.number().int().nonnegative(),
+    dueSourceCount: z.number().int().nonnegative(),
+    dueSourceIds: z.array(idSchema).max(10_000),
+    sources: z.array(sourceCollectionDueEntrySchema).max(10_000),
+}).strict().superRefine((value, ctx) => {
+    const due = value.sources.filter((row) => row.due).map((row) => row.sourceId);
+    if (value.sourceCount !== value.sources.length)
+        ctx.addIssue({ code: 'custom', path: ['sourceCount'], message: 'sourceCount must match sources' });
+    if (value.dueSourceCount !== due.length)
+        ctx.addIssue({ code: 'custom', path: ['dueSourceCount'], message: 'dueSourceCount must match due sources' });
+    if (JSON.stringify(value.dueSourceIds) !== JSON.stringify(due))
+        ctx.addIssue({ code: 'custom', path: ['dueSourceIds'], message: 'dueSourceIds must match ordered due sources' });
+});
+export const collectionTaskRunResultSchema = z.object({
+    taskId: idSchema,
+    targetId: sha256Schema,
+    sourceId: idSchema,
+    sourceRevisionRef: stableUriSchema,
+    observedAt: isoDateTimeSchema,
+    state: z.enum(['ACQUIRED', 'ACCESS_CONTROLLED', 'HTTP_TERMINAL', 'FAILED']),
+    finalLocator: stableUriSchema.nullable(),
+    httpStatus: z.number().int().min(100).max(599).nullable(),
+    evidenceRef: stableUriSchema.nullable(),
+    contentHash: sha256Schema.nullable(),
+    byteLength: z.number().int().nonnegative().nullable(),
+    mediaType: z.string().trim().min(1).max(256).nullable(),
+    reusedEvidence: z.boolean(),
+    relatedEvidenceRefs: z.array(stableUriSchema).max(512).default([]),
+    richDocumentRef: stableUriSchema.nullable().default(null),
+    projectionJobId: idSchema.optional(),
+    projectionState: z.enum(['PENDING', 'SUCCEEDED', 'PARTIAL', 'FAILED', 'NOT_REQUIRED']).optional(),
+    errorCode: z.string().trim().min(1).max(256).nullable(),
+}).strict().superRefine((value, ctx) => {
+    const acquired = value.state === 'ACQUIRED';
+    if (acquired && (!value.evidenceRef || !value.contentHash || value.byteLength === null || !value.mediaType))
+        ctx.addIssue({ code: 'custom', path: ['evidenceRef'], message: 'ACQUIRED result requires persisted Evidence identity' });
+    if (!acquired && (value.evidenceRef || value.contentHash || value.byteLength !== null || value.mediaType || value.reusedEvidence || value.relatedEvidenceRefs.length || value.richDocumentRef))
+        ctx.addIssue({ code: 'custom', path: ['evidenceRef'], message: 'non-ACQUIRED result cannot claim persisted Evidence' });
+    if (value.projectionState === 'PENDING' && (!value.projectionJobId || value.richDocumentRef || value.relatedEvidenceRefs.length || value.errorCode))
+        ctx.addIssue({ code: 'custom', path: ['projectionState'], message: 'pending projection requires a job and no derived result' });
+    if (value.projectionState === 'SUCCEEDED' && !value.richDocumentRef)
+        ctx.addIssue({ code: 'custom', path: ['projectionState'], message: 'successful projection requires a document' });
+    if (value.projectionState === 'PARTIAL' && (!acquired || !value.errorCode || !value.richDocumentRef))
+        ctx.addIssue({ code: 'custom', path: ['projectionState'], message: 'partial projection requires acquired Evidence, document and error' });
+    if (value.projectionState === 'NOT_REQUIRED' && value.richDocumentRef)
+        ctx.addIssue({ code: 'custom', path: ['projectionState'], message: 'unrequired projection cannot claim a document' });
+    if (value.projectionState === 'FAILED' && (!acquired || !value.errorCode || value.richDocumentRef))
+        ctx.addIssue({ code: 'custom', path: ['projectionState'], message: 'failed projection requires acquired raw Evidence, error and no document' });
+    if (!acquired && value.projectionState)
+        ctx.addIssue({ code: 'custom', path: ['projectionState'], message: 'projection requires acquired raw Evidence' });
+    if (value.state === 'FAILED' && !value.errorCode)
+        ctx.addIssue({ code: 'custom', path: ['errorCode'], message: 'FAILED result requires errorCode' });
+});
+export const collectionRunReceiptSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    projectRef: stableUriSchema,
+    batchId: idSchema,
+    batchRef: stableUriSchema,
+    runId: idSchema,
+    runtimeNodeId: idSchema,
+    startedAt: isoDateTimeSchema,
+    finishedAt: isoDateTimeSchema,
+    status: z.enum(['SUCCEEDED', 'PARTIAL', 'FAILED']),
+    results: z.array(collectionTaskRunResultSchema).min(1).max(10_000),
+}).strict().superRefine((value, ctx) => {
+    if (Date.parse(value.finishedAt) < Date.parse(value.startedAt))
+        ctx.addIssue({ code: 'custom', path: ['finishedAt'], message: 'finishedAt must not precede startedAt' });
+    const acquired = value.results.filter((row) => row.state === 'ACQUIRED').length;
+    const incomplete = value.results.some(row => row.projectionState === 'FAILED' || row.projectionState === 'PARTIAL');
+    const expected = acquired === 0 ? 'FAILED' : acquired === value.results.length && !incomplete ? 'SUCCEEDED' : 'PARTIAL';
+    if (value.status !== expected)
+        ctx.addIssue({ code: 'custom', path: ['status'], message: `status must be ${expected} for task results` });
+});

package/dist/internal/contracts/common.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export declare const schemaVersionSchema: z.ZodLiteral<1>;
+export declare const idSchema: z.ZodString;
+export declare const projectKeySchema: z.ZodString;
+export declare const isoDateTimeSchema: z.ZodISODateTime;
+export declare const sha256Schema: z.ZodString;
+export declare const stableUriSchema: z.ZodString;
+export declare const accessClassificationSchema: z.ZodEnum<{
+    PUBLIC: "PUBLIC";
+    PUBLIC_METADATA: "PUBLIC_METADATA";
+    TENANT: "TENANT";
+    INTERNAL: "INTERNAL";
+    FDE_INTERNAL: "FDE_INTERNAL";
+    ACCESS_CONTROLLED: "ACCESS_CONTROLLED";
+    UNKNOWN: "UNKNOWN";
+}>;
+export type AccessClassification = z.infer<typeof accessClassificationSchema>;

package/dist/internal/contracts/common.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export const schemaVersionSchema = z.literal(1);
+export const idSchema = z.string().trim().min(1).max(256);
+export const projectKeySchema = z.string().trim().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+export const isoDateTimeSchema = z.iso.datetime({ offset: true });
+export const sha256Schema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+export const stableUriSchema = z.string().trim().min(1).max(2048).regex(/^[a-z][a-z0-9+.-]*:\/\/.+/i);
+export const accessClassificationSchema = z.enum([
+    'PUBLIC',
+    'PUBLIC_METADATA',
+    'TENANT',
+    'INTERNAL',
+    'FDE_INTERNAL',
+    'ACCESS_CONTROLLED',
+    'UNKNOWN',
+]);