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

package/dist/errors.js

@@ -0,0 +1,7 @@
+import { AuthError, TenantManagementSdkError, ResourceSdkError, TenantOperationUnknownError } from '@native-knowledge/knowledge-sdk';
+import { agentEntryFailure } from './agent-entry-cli.js';
+/** A CLI failure never authorizes replay; retained phases remain partial completion. */
+export function cliFailure(e) {
+    const status = e instanceof AuthError || e instanceof TenantManagementSdkError || e instanceof ResourceSdkError ? e.status : 0, raw = e instanceof AuthError ? e.code : e instanceof TenantManagementSdkError || e instanceof ResourceSdkError ? e.code : e instanceof Error && e.name === 'ZodError' ? 'CLI_INPUT_INVALID' : e instanceof Error && /^[A-Z][A-Z0-9_]{1,100}$/.test(e.message) ? e.message : 'CLI_OPERATION_FAILED', code = /^[A-Z][A-Z0-9_]{1,100}$/.test(raw) ? raw : 'CLI_OPERATION_FAILED', exit = (e instanceof TenantManagementSdkError || e instanceof TenantOperationUnknownError) && e.completedPhase ? 7 : code.includes('UNKNOWN') || code.includes('INCOMPLETE') ? 7 : status === 403 || code.includes('FORBIDDEN') ? 4 : status === 409 || code.includes('CONFLICT') ? 5 : status >= 500 || code.includes('TRANSPORT') ? 6 : code.includes('AUTH_') ? 3 : 2;
+    return { exit, error: { code, status, ...(agentEntryFailure(e) ?? {}), retryable: false, nextActions: code === 'AUTH_LOGOUT_REQUIRED' ? [{ command: 'native-knowledge auth logout', automatic: false }] : code === 'AUTH_CREDENTIAL_SOURCE_CONFLICT' ? [{ command: 'native-knowledge help', automatic: false }] : e instanceof TenantOperationUnknownError && e.requestId ? [{ tool: 'tenant_operation_status', arguments: { requestId: e.requestId }, automatic: false, requiredScopes: ['knowledge.workflow.read'] }] : exit === 3 ? [{ command: 'native-knowledge auth login', automatic: false }] : code === 'CLI_LOCAL_ACCESS_REMOVED' ? [{ command: 'native-knowledge help', automatic: false, documentation: 'docs/operations/tenant-cli-migration.md' }] : [], ...((e instanceof TenantManagementSdkError || e instanceof TenantOperationUnknownError) ? { completedPhase: e.completedPhase, ref: e.ref } : {}), ...(e instanceof TenantOperationUnknownError ? { requestId: e.requestId } : {}) } };
+}

package/dist/input.js

@@ -0,0 +1,89 @@
+import { open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { AuthError } from '@native-knowledge/knowledge-sdk';
+import { localFlags, retired } from './commands.js';
+const values = ['server', 'profile', 'config-dir', 'client-id', 'scope', 'authority-version', 'callback-port', 'timeout-seconds', 'token-file', 'tenant-id', 'input-file', 'input-json', 'arguments-file', 'content-file', 'tool', 'name', 'ref', 'query', 'after', 'limit', 'project-key', 'project-ref', 'source-id', 'request-id', 'job-ref', 'expected-epoch', 'expected-version', 'expected-generation', 'action', 'output-file', 'output', 'range', 'expected-content-hash', 'kind', 'index', 'state-index', 'resource-type', 'source-project', 'ref-prefix', 'after-ordinal', 'document-ref', 'category', 'goal'];
+const booleans = ['human', 'json', 'help', 'non-interactive', 'no-browser', 'allow-insecure-http', 'head', 'all', 'guided'];
+export function parse(argv) { const words = [], flags = new Map(); for (let i = 0; i < argv.length; i++) {
+    const s = argv[i];
+    if (!s.startsWith('--')) {
+        words.push(s);
+        continue;
+    }
+    const k = s.slice(2);
+    if (retired.has(words.join(' ')) || localFlags.has(k))
+        throw new AuthError('CLI_LOCAL_ACCESS_REMOVED');
+    if (!values.includes(k) && !booleans.includes(k))
+        throw new AuthError('CLI_INPUT_INVALID');
+    const v = booleans.includes(k) ? 'true' : argv[++i];
+    if (!v || v.startsWith('--') || flags.has(k) && k !== 'scope')
+        throw new AuthError('CLI_INPUT_INVALID');
+    flags.set(k, [...(flags.get(k) ?? []), v]);
+} return { command: words.join(' '), flags }; }
+export function one(f, k, required = false) { const v = f.get(k)?.[0]; if (required && !v)
+    throw new AuthError('CLI_INPUT_REQUIRED'); return v; }
+export function integer(f, k, fallback, min, max) { const raw = one(f, k), n = raw === undefined ? fallback : Number(raw); if (!Number.isSafeInteger(n) || n < min || n > max)
+    throw new AuthError('CLI_INPUT_INVALID'); return n; }
+export async function smallFile(file, max) { const h = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW); try {
+    const s = await h.stat();
+    if (!s.isFile() || s.size > max)
+        throw new AuthError('CLI_INPUT_BUDGET');
+    const b = Buffer.alloc(max + 1);
+    let n = 0;
+    while (n < b.length) {
+        const p = await h.read(b, n, b.length - n, n);
+        if (!p.bytesRead)
+            break;
+        n += p.bytesRead;
+    }
+    if (n > max)
+        throw new AuthError('CLI_INPUT_BUDGET');
+    return b.subarray(0, n);
+}
+finally {
+    await h.close();
+} }
+export async function argumentsFor(f, command) {
+    const file = one(f, 'input-file') ?? one(f, 'arguments-file'), json = one(f, 'input-json');
+    if (file && json || f.has('input-file') && f.has('arguments-file'))
+        throw new AuthError('CLI_INPUT_CONFLICT');
+    let input = {};
+    if (file || json) {
+        const text = file ? (await smallFile(file, 131072)).toString('utf8') : json;
+        if (Buffer.byteLength(text) > 131072)
+            throw new AuthError('CLI_INPUT_BUDGET');
+        try {
+            input = JSON.parse(text);
+        }
+        catch {
+            throw new AuthError('CLI_INPUT_INVALID');
+        }
+        if (!input || typeof input !== 'object' || Array.isArray(input))
+            throw new AuthError('CLI_INPUT_INVALID');
+    }
+    for (const k of ['ref', 'query', 'after', 'limit', 'project-key', 'project-ref', 'source-id', 'request-id', 'job-ref', 'expected-epoch', 'expected-version', 'expected-generation', 'action', 'kind', 'index', 'state-index', 'resource-type', 'source-project', 'ref-prefix', 'after-ordinal', 'document-ref']) {
+        const v = one(f, k);
+        if (v === undefined)
+            continue;
+        const camel = k.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+        if (Object.hasOwn(input, camel))
+            throw new AuthError('CLI_INPUT_CONFLICT');
+        input[camel] = ['limit', 'expected-epoch', 'expected-version', 'expected-generation', 'index', 'state-index', 'after-ordinal'].includes(k) ? integer(f, k, 0, 0, Number.MAX_SAFE_INTEGER) : v;
+    }
+    if (command.startsWith('web-collect ') && ['pause', 'resume', 'cancel'].includes(command.split(' ')[1])) {
+        if (input.action !== undefined)
+            throw new AuthError('CLI_INPUT_CONFLICT');
+        input.action = command.split(' ')[1].toUpperCase();
+    }
+    if (command === 'insight compose') {
+        if (input.outputKind !== undefined && input.outputKind !== 'INSIGHT')
+            throw new AuthError('CLI_INPUT_CONFLICT');
+        input.outputKind = 'INSIGHT';
+    }
+    if (f.has('content-file')) {
+        if (!['agent submit', 'artifact draft', 'tool call'].includes(command) || Object.hasOwn(input, 'contentBase64'))
+            throw new AuthError('CLI_INPUT_CONFLICT');
+        input.contentBase64 = (await smallFile(one(f, 'content-file', true), 65536)).toString('base64');
+    }
+    return input;
+}

package/dist/internal/contracts/artifact.js

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { accessClassificationSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema, } from './common.js';
+export const artifactIdSchema = z.string().trim().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+export const artifactKindSchema = z.enum([
+    'SIGNAL_GENERATION',
+    'RESEARCH',
+    'REVIEW',
+    'KNOWLEDGE',
+    'INSIGHT',
+]);
+export const artifactStatusSchema = z.enum([
+    'GENERATED',
+    'DRAFT',
+    'READY_FOR_REVIEW',
+    'REWORK_REQUIRED',
+    'APPROVED',
+    'REJECTED',
+    'SUPERSEDED',
+]);
+export const artifactManifestSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    artifactId: artifactIdSchema,
+    kind: artifactKindSchema,
+    projectKey: projectKeySchema,
+    projectRef: stableUriSchema.optional(),
+    version: z.number().int().positive(),
+    ref: stableUriSchema,
+    identityRef: stableUriSchema,
+    status: artifactStatusSchema,
+    access: accessClassificationSchema.default('INTERNAL'),
+    title: z.string().trim().min(1).max(500).optional(),
+    createdAt: isoDateTimeSchema,
+    observedAt: isoDateTimeSchema.nullable().default(null),
+    validUntil: isoDateTimeSchema.nullable().default(null),
+    contentHash: sha256Schema,
+    mediaType: z.string().trim().min(1).max(256),
+    byteLength: z.number().int().nonnegative(),
+    evidenceRefs: z.array(stableUriSchema).max(256).default([]),
+    relatedRefs: z.array(stableUriSchema).max(256).default([]),
+    supersedesRef: stableUriSchema.nullable().default(null),
+}).strict().superRefine((value, ctx) => {
+    if (value.projectRef) {
+        try {
+            const url = new URL(value.projectRef);
+            if (url.protocol !== 'knowledge-project:' || url.hostname.toLowerCase() !== value.projectKey.toLowerCase())
+                ctx.addIssue({ code: 'custom', path: ['projectRef'], message: 'projectRef project must match Artifact project' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['projectRef'], message: 'Invalid projectRef' });
+        }
+    }
+    if (value.validUntil && value.observedAt && Date.parse(value.validUntil) < Date.parse(value.observedAt)) {
+        ctx.addIssue({ code: 'custom', path: ['validUntil'], message: 'validUntil must not precede observedAt' });
+    }
+    if (value.kind === 'SIGNAL_GENERATION' && (value.version !== 1 || value.status !== 'GENERATED')) {
+        ctx.addIssue({ code: 'custom', path: ['version'], message: 'Signal generations are immutable generated artifacts at version 1' });
+    }
+    if (['KNOWLEDGE', 'INSIGHT'].includes(value.kind) && value.status === 'GENERATED') {
+        ctx.addIssue({ code: 'custom', path: ['status'], message: 'Knowledge/Insight cannot use GENERATED status' });
+    }
+});
+export const artifactWriteMetadataSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    artifactId: artifactIdSchema,
+    kind: artifactKindSchema,
+    projectKey: projectKeySchema,
+    projectRef: stableUriSchema.optional(),
+    version: z.number().int().positive(),
+    status: artifactStatusSchema,
+    access: accessClassificationSchema.default('INTERNAL'),
+    title: z.string().trim().min(1).max(500).optional(),
+    createdAt: isoDateTimeSchema,
+    observedAt: isoDateTimeSchema.nullable().default(null),
+    validUntil: isoDateTimeSchema.nullable().default(null),
+    mediaType: z.string().trim().min(1).max(256),
+    evidenceRefs: z.array(stableUriSchema).max(256).default([]),
+    relatedRefs: z.array(stableUriSchema).max(256).default([]),
+    supersedesRef: stableUriSchema.nullable().default(null),
+}).strict().superRefine((value, ctx) => {
+    if (value.validUntil && value.observedAt && Date.parse(value.validUntil) < Date.parse(value.observedAt)) {
+        ctx.addIssue({ code: 'custom', path: ['validUntil'], message: 'validUntil must not precede observedAt' });
+    }
+    if (value.kind === 'SIGNAL_GENERATION') {
+        ctx.addIssue({ code: 'custom', path: ['kind'], message: 'Signal generations are produced only by the signal composer' });
+    }
+    if (value.kind === 'REVIEW') {
+        ctx.addIssue({ code: 'custom', path: ['kind'], message: 'Review artifacts are produced only by the review lifecycle' });
+    }
+    if (['KNOWLEDGE', 'INSIGHT'].includes(value.kind) && value.status !== 'DRAFT') {
+        ctx.addIssue({ code: 'custom', path: ['status'], message: 'Knowledge/Insight manual writes must enter as DRAFT' });
+    }
+    if (value.kind === 'RESEARCH' && value.status !== 'DRAFT') {
+        ctx.addIssue({ code: 'custom', path: ['status'], message: 'Research manual writes must enter as DRAFT' });
+    }
+});
+export const reviewDecisionSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    targetRef: stableUriSchema,
+    decision: z.enum(['PASS', 'REWORK', 'REJECT']),
+    reviewedAt: isoDateTimeSchema,
+    summary: z.string().trim().min(1).max(16000),
+    evidenceRefs: z.array(stableUriSchema).max(256).default([]),
+}).strict();

package/dist/internal/contracts/collection-control.js

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, stableUriSchema } from './common.js';
+export const knowledgeControlScopeSchema = z.enum([
+    'knowledge.read',
+    'knowledge.collect',
+    'knowledge.source.manage',
+    'knowledge.review',
+    'knowledge.publish',
+]);
+export const collectionControlRequestIdSchema = idSchema.regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/);
+export const collectionControlCreateRequestSchema = z.object({
+    projectKey: projectKeySchema,
+    requestId: collectionControlRequestIdSchema,
+    sourceIds: z.array(idSchema).min(1).max(1_000),
+}).strict().transform((value) => ({
+    ...value,
+    sourceIds: [...new Set(value.sourceIds)].sort(),
+}));
+export const collectionControlAuditSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    requestId: collectionControlRequestIdSchema,
+    batchId: idSchema,
+    batchRef: stableUriSchema,
+    tenantId: idSchema,
+    clientId: idSchema,
+    requestedAt: isoDateTimeSchema,
+    sourceIds: z.array(idSchema).min(1).max(1_000),
+    sourceRevisionRefs: z.array(stableUriSchema).min(1).max(1_000),
+    admission: z.literal('ACCEPTED'),
+}).strict().superRefine((value, ctx) => {
+    if (value.sourceIds.length !== value.sourceRevisionRefs.length)
+        ctx.addIssue({
+            code: 'custom',
+            path: ['sourceRevisionRefs'],
+            message: 'sourceRevisionRefs must align with sourceIds',
+        });
+});
+export const collectionControlStatusSchema = z.enum(['PENDING', 'SUCCEEDED', 'PARTIAL', 'FAILED']);
+export const collectionControlRunSummarySchema = z.object({
+    runId: idSchema,
+    runtimeNodeId: idSchema,
+    startedAt: isoDateTimeSchema,
+    finishedAt: isoDateTimeSchema,
+    status: z.enum(['SUCCEEDED', 'PARTIAL', 'FAILED']),
+}).strict();
+export const collectionControlRequestProjectionSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    requestId: collectionControlRequestIdSchema,
+    batchId: idSchema,
+    batchRef: stableUriSchema,
+    trigger: z.literal('MANUAL'),
+    status: collectionControlStatusSchema,
+    requestedAt: isoDateTimeSchema,
+    requestedBy: z.object({ tenantId: idSchema, clientId: idSchema }).strict(),
+    sourceIds: z.array(idSchema).min(1).max(1_000),
+    sourceRevisionRefs: z.array(stableUriSchema).min(1).max(1_000),
+    run: collectionControlRunSummarySchema.nullable(),
+}).strict();
+export const collectionControlCreateResponseSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    inserted: z.boolean(),
+    request: collectionControlRequestProjectionSchema,
+}).strict();
+export const collectionControlGetResponseSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    request: collectionControlRequestProjectionSchema,
+}).strict();

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.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',
+]);