@native-knowledge/cli 0.1.0-rc.1 → 0.1.0-rc.3

package/dist/commands.js

@@ -0,0 +1,41 @@
+/** 固定别名映射到原生工具；不存在可回退本地执行的分支。 */
+export const commands = {
+    'agent guide': 'tenant_workflow_guide', 'agent plan': 'tenant_workflow_plan', 'agent advance': 'tenant_workflow_advance', 'agent submit': 'tenant_material_submit', 'agent status': 'tenant_workflow_plan',
+    'source list': 'tenant_source_list', 'source get': 'tenant_source_get', 'source define': 'tenant_source_define', 'source configure': 'tenant_source_configure',
+    'collection request': 'tenant_collection_request', 'collection status': 'tenant_collection_status',
+    'project list': 'tenant_project_list', 'project get': 'tenant_project_get', 'project materials': 'tenant_project_materials', 'project scope-set': 'tenant_project_scope_set', 'project lifecycle-set': 'tenant_project_lifecycle_set',
+    'runtime status': 'tenant_runtime_status', 'work queue': 'tenant_work_queue',
+    'artifact draft': 'tenant_artifact_draft', 'artifact review': 'tenant_knowledge_review', 'artifact promote': 'tenant_artifact_promote', 'knowledge compose': 'tenant_knowledge_compose', 'insight compose': 'tenant_knowledge_compose', 'knowledge read': 'tenant_knowledge_read',
+    'material share': 'tenant_material_share', 'material revoke': 'tenant_material_revoke', 'material routes': 'tenant_material_routes', 'snapshot declare': 'tenant_snapshot_declare', 'snapshot status': 'tenant_snapshot_status',
+};
+for (const op of ['list', 'describe', 'read', 'search', 'counts', 'window', 'changes', 'capabilities', 'media', 'index-status'])
+    commands['resource ' + op] = 'knowledge_resource_' + op.replaceAll('-', '_');
+for (const op of ['preview', 'submit', 'status', 'results', 'cycles', 'read', 'pause', 'resume', 'cancel', 'refresh', 'index-status'])
+    commands['web-collect ' + op] = 'tenant_web_collect_' + (['pause', 'resume', 'cancel'].includes(op) ? 'control' : op.replaceAll('-', '_'));
+export const localFlags = new Set(['data-root', 'identity-database', 'node-id', 'tenant', 'user', 'agent', 'cursor-secret-env', 'file-roots', 'browser-fallback', 'projection-mode', 'consumer-profile-file']);
+export const retired = new Set(['project-intent put', 'project-intent get', 'source put', 'source preview', 'source add-url', 'source add-file', 'source add-executor', 'source reproject', 'source drift', 'source rebind', 'source due', 'batch create', 'batch create-due', 'batch get', 'batch collector-view', 'batch run', 'batch run-get', 'material page', 'material describe', 'material scope get', 'material scope set', 'material status', 'material publish', 'material location select', 'material put', 'artifact create', 'artifact get', 'artifact list', 'artifact index', 'artifact support', 'reference gap-audit', 'delivery content-factory project', 'delivery content-factory stage', 'delivery content-factory outbox-list', 'delivery content-factory record']);
+export const help = { name: 'native-knowledge', alias: 'knowledge-v2', schemaVersion: 1, transport: 'REMOTE_OAUTH_TENANT', commands: ['auth login|status|whoami|logout', 'profile list|use|remove', 'discover', 'tool list|describe|call', 'resource file', 'agent find', 'agent tool', 'agent call', 'agent task', 'agent input', ...Object.keys(commands)], input: '--input-file <JSON> | --input-json <JSON>; --content-file <file> for submit/draft', connection: '--server <API-root> --profile <name> --token-file <file> --tenant-id <expected-Tenant>', login: 'auth login --server <API-root> --client-id <registered-native-client> [--scope <scope> ...] [--authority-version 1|2] [--no-browser] [--callback-port <port>]', rules: ['Tenant identity comes from the server session. Project is an explicit narrowing.', 'No database, local collection or Host maintenance access.', 'Noninteractive business calls never open a browser. stdout is one JSON result.'] };
+/** Local command names also drive offline help; live schemas remain server-owned. */
+export const localCommands = [
+    'auth login', 'auth status', 'auth whoami', 'auth logout', 'profile list', 'profile use', 'profile remove',
+    'discover', 'tool list', 'tool describe', 'tool call', 'resource file',
+    'agent find', 'agent tool', 'agent call', 'agent task', 'agent input',
+];
+export const commandNames = [...localCommands, ...Object.keys(commands)];
+export function commandHelp(topic = '') {
+    const groups = [...new Set(commandNames.filter(name => name.includes(' ')).map(name => name.split(' ')[0]))];
+    if (!topic)
+        return { ...help, groups, help: 'native-knowledge help [<group> [<command>]]' };
+    const selected = commandNames.filter(name => name === topic || name.startsWith(topic + ' '));
+    if (!selected.length)
+        return undefined;
+    return {
+        name: help.name, alias: help.alias, schemaVersion: help.schemaVersion, transport: help.transport,
+        topic, commands: selected, input: help.input, connection: help.connection, rules: help.rules,
+        ...(topic === 'auth' || topic === 'auth login' ? { login: help.login } : {}),
+        ...(commands[topic] && topic !== 'agent status' ? {
+            tool: commands[topic], schema: `native-knowledge tool describe --tool ${commands[topic]}`,
+        } : {}),
+        help: 'Use a command with --help; authenticated tool describe returns the current schema and availability.',
+    };
+}

package/dist/download.js

@@ -0,0 +1,45 @@
+import { open, unlink } from 'node:fs/promises';
+import { createWriteStream } from 'node:fs';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createHash } from 'node:crypto';
+import { AuthError } from '@native-knowledge/knowledge-sdk';
+import { one } from './input.js';
+export async function download(client, f, input) {
+    if (typeof input.ref !== 'string')
+        throw new AuthError('CLI_INPUT_REQUIRED');
+    const output = one(f, 'output-file') ?? one(f, 'output');
+    if (!f.has('head') && !output)
+        throw new AuthError('CLI_INPUT_REQUIRED');
+    const response = await client.resources.stream(input.ref, { ...(f.has('head') ? { head: true } : {}), ...(one(f, 'range') ? { range: one(f, 'range') } : {}), ...(one(f, 'expected-content-hash') ? { expectedContentHash: one(f, 'expected-content-hash') } : {}), ...(typeof input.projectRef === 'string' ? { projectRef: input.projectRef } : {}) });
+    const { body, ...metadata } = response;
+    if (f.has('head'))
+        return metadata;
+    if (!body)
+        throw new AuthError('CLI_TRANSFER_FAILED');
+    let handle;
+    try {
+        handle = await open(output, 'wx', 0o600);
+    }
+    catch {
+        await body.cancel();
+        throw new AuthError('CLI_OUTPUT_EXISTS_OR_UNAVAILABLE');
+    }
+    const hash = createHash('sha256');
+    let bytes = 0;
+    try {
+        await pipeline(Readable.fromWeb(body), new Transform({ transform(chunk, _encoding, done) { bytes += chunk.length; if (bytes > response.contentLength)
+                return done(new AuthError('CLI_TRANSFER_FAILED')); hash.update(chunk); done(null, chunk); } }), createWriteStream(output, { fd: handle.fd, autoClose: false }));
+        if (bytes !== response.contentLength || response.status !== 206 && 'sha256:' + hash.digest('hex') !== response.contentHash)
+            throw new AuthError('CLI_TRANSFER_INTEGRITY');
+        await handle.sync();
+        return { ...metadata, bytes, verification: response.status === 206 ? 'RANGE_BYTES_RECEIVED' : 'CLIENT_FULL_HASH_VERIFIED' };
+    }
+    catch {
+        await unlink(output).catch(() => { });
+        throw new AuthError('CLI_TRANSFER_FAILED');
+    }
+    finally {
+        await handle.close();
+    }
+}

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