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

package/dist/internal/serving-contracts/tenant-workspace.js

@@ -0,0 +1,28 @@
+/** Provider18 adds explicit metadata reads; Provider17 remains the exact original twenty tools. */
+import { z } from 'zod';
+import { tenantResourceRefSchema, tenantSourceIdSchema, collectionRefreshSchema, stableUriSchema, isoDateTimeSchema, materialTenantIdSchema } from '../contracts/index.js';
+import { tenantManagementToolSchemas, tenantManagementDataSchemas, tenantManagementScopesForInput, tenantManagementAuthorization, tenantManagementProviderBaseSchema, tenantManagementErrorSchema } from './tenant-management.js';
+const page = { after: z.string().min(1).max(4096).optional(), limit: z.number().int().min(1).max(100).optional() };
+export const tenantWorkStageSchema = z.enum(['ALL', 'RESEARCH', 'DRAFT', 'READY_FOR_REVIEW', 'REWORK_REQUIRED', 'APPROVED']);
+export const tenantWorkspaceExtraToolSchemas = { tenant_source_inventory: z.object(page).strict(), tenant_work_queue: z.object({ ...page, stage: tenantWorkStageSchema.default('ALL') }).strict() };
+const source = z.object({ sourceId: tenantSourceIdSchema, title: z.string().min(1).max(512).nullable(), revisionRef: stableUriSchema.nullable(), generation: z.number().int().positive().safe().nullable(), paused: z.boolean().nullable(), tenantEnabled: z.boolean().nullable(), refresh: collectionRefreshSchema.nullable(), canonicalState: z.enum(['READY', 'UNAVAILABLE', 'INTEGRITY_MISMATCH']) }).strict();
+const artifact = z.object({ ref: tenantResourceRefSchema, title: z.string().max(512), kind: z.string().max(128).nullable(), status: z.string().max(128).nullable(), version: z.number().int().positive().safe().nullable(), recordedAt: isoDateTimeSchema.nullable(), availability: z.enum(['READY', 'UNAVAILABLE', 'INTEGRITY_MISMATCH']), succession: z.enum(['SUCCESSOR_VISIBLE', 'NO_VISIBLE_SUCCESSOR', 'UNCONFIRMED']) }).strict();
+export const tenantWorkspaceExtraDataSchemas = {
+    tenant_source_inventory: z.object({ items: z.array(source).max(100), nextAfter: z.string().max(4096).nullable(), coverage: z.literal('REGISTERED_TENANT_SOURCES') }).strict(),
+    tenant_work_queue: z.object({ items: z.array(artifact).max(100), nextAfter: z.string().max(4096).nullable(), stage: tenantWorkStageSchema, candidateCount: z.number().int().min(0).max(100), coverage: z.literal('AUTHORIZED_NATIVE_ARTIFACT_METADATA'), total: z.null() }).strict(),
+};
+export const tenantWorkspaceToolSchemas = { ...tenantManagementToolSchemas, ...tenantWorkspaceExtraToolSchemas };
+export const tenantWorkspaceDataSchemas = { ...tenantManagementDataSchemas, ...tenantWorkspaceExtraDataSchemas };
+export function tenantWorkspaceScopesForInput(name, raw) { if (name === 'tenant_source_inventory') {
+    tenantWorkspaceExtraToolSchemas[name].parse(raw);
+    return ['knowledge.source.read'];
+} if (name === 'tenant_work_queue') {
+    tenantWorkspaceExtraToolSchemas[name].parse(raw);
+    return ['knowledge.workflow.read'];
+} return tenantManagementScopesForInput(name, raw); }
+export function tenantWorkspaceAuthorization(name) { return name === 'tenant_source_inventory' || name === 'tenant_work_queue' ? { selection: 'FIXED', scopeAlternatives: [[name === 'tenant_source_inventory' ? 'knowledge.source.read' : 'knowledge.workflow.read']] } : tenantManagementAuthorization(name); }
+export function tenantWorkspaceEnvelopeSchema(tool) { return z.object({ schemaVersion: z.literal(2), tenantId: materialTenantIdSchema, tool: z.literal(tool), data: tenantWorkspaceDataSchemas[tool] }).strict(); }
+export const tenantWorkspaceInputJsonSchemas = Object.fromEntries(Object.entries(tenantWorkspaceToolSchemas).map(([name, schema]) => [name, z.toJSONSchema(schema, { target: 'draft-07' })]));
+export const tenantWorkspaceOutputJsonSchemas = Object.fromEntries(Object.keys(tenantWorkspaceToolSchemas).map(name => [name, { type: 'object', oneOf: [z.toJSONSchema(tenantWorkspaceEnvelopeSchema(name), { target: 'draft-07' }), z.toJSONSchema(tenantManagementErrorSchema, { target: 'draft-07' })] }]));
+export const tenantWorkspaceProviderSchema = tenantManagementProviderBaseSchema.extend({ schemaVersion: z.literal(18), tools: z.array(z.string()).length(Object.keys(tenantWorkspaceToolSchemas).length), capabilities: z.tuple([z.literal('TENANT_MANAGEMENT_V1'), z.literal('TENANT_WORKFLOW_V1'), z.literal('TENANT_CURRENTNESS_V2'), z.literal('TENANT_SOURCE_V1'), z.literal('TENANT_WORKSPACE_METADATA_V1')]) }).strict().superRefine((value, ctx) => { if (new Set(value.tools).size !== Object.keys(tenantWorkspaceToolSchemas).length || value.tools.some(name => !Object.hasOwn(tenantWorkspaceToolSchemas, name)))
+    ctx.addIssue({ code: 'custom', message: 'Workspace tools must match the exact version18 contract' }); });

package/dist/internal/serving-contracts/workflow.d.ts

@@ -0,0 +1,439 @@
+/** Agent 的治理合同描述真实状态和下一步，不把写入权限解释为审核或正文权限。 */
+import { z } from 'zod';
+export declare const workflowPlanInputSchema: z.ZodObject<{
+    projectRef: z.ZodString;
+    ref: z.ZodString;
+}, z.core.$strict>;
+export declare const workflowGuideInputSchema: z.ZodObject<{
+    projectRef: z.ZodString;
+}, z.core.$strict>;
+export declare const workflowActionSchema: z.ZodEnum<{
+    SUBMIT_REVIEW: "SUBMIT_REVIEW";
+    FINALIZE_REVIEW: "FINALIZE_REVIEW";
+    PREPARE_SOURCE: "PREPARE_SOURCE";
+    REGISTER: "REGISTER";
+}>;
+export declare const workflowAdvanceInputSchema: z.ZodObject<{
+    projectRef: z.ZodString;
+    ref: z.ZodString;
+    action: z.ZodEnum<{
+        SUBMIT_REVIEW: "SUBMIT_REVIEW";
+        FINALIZE_REVIEW: "FINALIZE_REVIEW";
+        PREPARE_SOURCE: "PREPARE_SOURCE";
+        REGISTER: "REGISTER";
+    }>;
+    expectedVersion: z.ZodOptional<z.ZodNumber>;
+    actedAt: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strict>;
+export declare const agentSubmitInputSchema: z.ZodObject<{
+    projectRef: z.ZodString;
+    sourceId: z.ZodString;
+    contentBase64: z.ZodString;
+    mediaType: z.ZodString;
+    access: z.ZodDefault<z.ZodEnum<{
+        PUBLIC: "PUBLIC";
+        TENANT: "TENANT";
+        INTERNAL: "INTERNAL";
+        FDE_INTERNAL: "FDE_INTERNAL";
+    }>>;
+    submittedAt: z.ZodOptional<z.ZodISODateTime>;
+    freshnessSeconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const workflowNextActionSchema: z.ZodObject<{
+    id: z.ZodString;
+    tool: z.ZodNullable<z.ZodString>;
+    arguments: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+    requiredScopes: z.ZodArray<z.ZodString>;
+    missingScopes: z.ZodArray<z.ZodString>;
+    missingFields: z.ZodArray<z.ZodString>;
+    canExecute: z.ZodBoolean;
+    automatic: z.ZodBoolean;
+    reasonCode: z.ZodString;
+    cli: z.ZodObject<{
+        command: z.ZodString;
+        flags: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+    }, z.core.$strict>;
+    http: z.ZodObject<{
+        method: z.ZodLiteral<"POST">;
+        path: z.ZodLiteral<"/mcp/management">;
+        tool: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+declare const readDecision: z.ZodObject<{
+    action: z.ZodEnum<{
+        ALLOW: "ALLOW";
+        REVIEW_REQUIRED: "REVIEW_REQUIRED";
+        DENY: "DENY";
+    }>;
+    reasonCodes: z.ZodArray<z.ZodString>;
+    authority: z.ZodEnum<{
+        AUTHENTICATED_READER: "AUTHENTICATED_READER";
+        LOCAL_PROFILE_SIMULATION: "LOCAL_PROFILE_SIMULATION";
+    }>;
+}, z.core.$strict>;
+export declare const workflowPlanSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    projectRef: z.ZodString;
+    ref: z.ZodString;
+    contentHash: z.ZodString;
+    kind: z.ZodString;
+    version: z.ZodNullable<z.ZodNumber>;
+    status: z.ZodUnion<[z.ZodEnum<{
+        GENERATED: "GENERATED";
+        DRAFT: "DRAFT";
+        READY_FOR_REVIEW: "READY_FOR_REVIEW";
+        REWORK_REQUIRED: "REWORK_REQUIRED";
+        APPROVED: "APPROVED";
+        REJECTED: "REJECTED";
+        SUPERSEDED: "SUPERSEDED";
+    }>, z.ZodEnum<{
+        RAW_MATERIAL: "RAW_MATERIAL";
+        RAW_EVIDENCE: "RAW_EVIDENCE";
+    }>]>;
+    productionPhase: z.ZodEnum<{
+        REGISTERED: "REGISTERED";
+        PERSISTED: "PERSISTED";
+        CATALOG_PROJECTED: "CATALOG_PROJECTED";
+    }>;
+    rawMaterialAvailable: z.ZodNullable<z.ZodBoolean>;
+    readiness: z.ZodNullable<z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        profile: z.ZodEnum<{
+            HUMAN_ARTICLE_V1: "HUMAN_ARTICLE_V1";
+            KNOWLEDGE_CARD_V1: "KNOWLEDGE_CARD_V1";
+        }>;
+        ready: z.ZodBoolean;
+        reasons: z.ZodArray<z.ZodEnum<{
+            ROLE_MISMATCH: "ROLE_MISMATCH";
+            TITLE_REQUIRED: "TITLE_REQUIRED";
+            SUMMARY_REQUIRED: "SUMMARY_REQUIRED";
+            TEXT_TOO_SHORT: "TEXT_TOO_SHORT";
+            STRUCTURE_TOO_THIN: "STRUCTURE_TOO_THIN";
+            SOURCE_EVIDENCE_REQUIRED: "SOURCE_EVIDENCE_REQUIRED";
+            CITATION_COVERAGE_REQUIRED: "CITATION_COVERAGE_REQUIRED";
+            EVIDENCE_MISMATCH: "EVIDENCE_MISMATCH";
+            MEDIA_UNAVAILABLE: "MEDIA_UNAVAILABLE";
+        }>>;
+        metrics: z.ZodObject<{
+            textCharacters: z.ZodNumber;
+            blockCount: z.ZodNumber;
+            textBlockCount: z.ZodNumber;
+            mediaBlockCount: z.ZodNumber;
+            sourceEvidenceCount: z.ZodNumber;
+            citationCount: z.ZodNumber;
+            citedBlockCount: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    reviewRef: z.ZodNullable<z.ZodString>;
+    reviewDecision: z.ZodNullable<z.ZodEnum<{
+        PASS: "PASS";
+        REWORK: "REWORK";
+        REJECT: "REJECT";
+    }>>;
+    support: z.ZodNullable<z.ZodObject<{
+        action: z.ZodEnum<{
+            ALLOW: "ALLOW";
+            REVIEW_REQUIRED: "REVIEW_REQUIRED";
+            DENY: "DENY";
+        }>;
+        reasonCodes: z.ZodArray<z.ZodString>;
+        missingEvidenceRefs: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    governedPolicyReady: z.ZodBoolean;
+    consumerReadDecision: z.ZodNullable<z.ZodObject<{
+        action: z.ZodEnum<{
+            ALLOW: "ALLOW";
+            REVIEW_REQUIRED: "REVIEW_REQUIRED";
+            DENY: "DENY";
+        }>;
+        reasonCodes: z.ZodArray<z.ZodString>;
+        authority: z.ZodEnum<{
+            AUTHENTICATED_READER: "AUTHENTICATED_READER";
+            LOCAL_PROFILE_SIMULATION: "LOCAL_PROFILE_SIMULATION";
+        }>;
+    }, z.core.$strict>>;
+    externalReady: z.ZodBoolean;
+    successorRef: z.ZodNullable<z.ZodString>;
+    blockers: z.ZodArray<z.ZodString>;
+    nextActions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        tool: z.ZodNullable<z.ZodString>;
+        arguments: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+        requiredScopes: z.ZodArray<z.ZodString>;
+        missingScopes: z.ZodArray<z.ZodString>;
+        missingFields: z.ZodArray<z.ZodString>;
+        canExecute: z.ZodBoolean;
+        automatic: z.ZodBoolean;
+        reasonCode: z.ZodString;
+        cli: z.ZodObject<{
+            command: z.ZodString;
+            flags: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+        }, z.core.$strict>;
+        http: z.ZodObject<{
+            method: z.ZodLiteral<"POST">;
+            path: z.ZodLiteral<"/mcp/management">;
+            tool: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const workflowAdvanceResultSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    action: z.ZodEnum<{
+        SUBMIT_REVIEW: "SUBMIT_REVIEW";
+        FINALIZE_REVIEW: "FINALIZE_REVIEW";
+        PREPARE_SOURCE: "PREPARE_SOURCE";
+        REGISTER: "REGISTER";
+    }>;
+    previousRef: z.ZodString;
+    inserted: z.ZodBoolean;
+    plan: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        projectRef: z.ZodString;
+        ref: z.ZodString;
+        contentHash: z.ZodString;
+        kind: z.ZodString;
+        version: z.ZodNullable<z.ZodNumber>;
+        status: z.ZodUnion<[z.ZodEnum<{
+            GENERATED: "GENERATED";
+            DRAFT: "DRAFT";
+            READY_FOR_REVIEW: "READY_FOR_REVIEW";
+            REWORK_REQUIRED: "REWORK_REQUIRED";
+            APPROVED: "APPROVED";
+            REJECTED: "REJECTED";
+            SUPERSEDED: "SUPERSEDED";
+        }>, z.ZodEnum<{
+            RAW_MATERIAL: "RAW_MATERIAL";
+            RAW_EVIDENCE: "RAW_EVIDENCE";
+        }>]>;
+        productionPhase: z.ZodEnum<{
+            REGISTERED: "REGISTERED";
+            PERSISTED: "PERSISTED";
+            CATALOG_PROJECTED: "CATALOG_PROJECTED";
+        }>;
+        rawMaterialAvailable: z.ZodNullable<z.ZodBoolean>;
+        readiness: z.ZodNullable<z.ZodObject<{
+            schemaVersion: z.ZodLiteral<1>;
+            profile: z.ZodEnum<{
+                HUMAN_ARTICLE_V1: "HUMAN_ARTICLE_V1";
+                KNOWLEDGE_CARD_V1: "KNOWLEDGE_CARD_V1";
+            }>;
+            ready: z.ZodBoolean;
+            reasons: z.ZodArray<z.ZodEnum<{
+                ROLE_MISMATCH: "ROLE_MISMATCH";
+                TITLE_REQUIRED: "TITLE_REQUIRED";
+                SUMMARY_REQUIRED: "SUMMARY_REQUIRED";
+                TEXT_TOO_SHORT: "TEXT_TOO_SHORT";
+                STRUCTURE_TOO_THIN: "STRUCTURE_TOO_THIN";
+                SOURCE_EVIDENCE_REQUIRED: "SOURCE_EVIDENCE_REQUIRED";
+                CITATION_COVERAGE_REQUIRED: "CITATION_COVERAGE_REQUIRED";
+                EVIDENCE_MISMATCH: "EVIDENCE_MISMATCH";
+                MEDIA_UNAVAILABLE: "MEDIA_UNAVAILABLE";
+            }>>;
+            metrics: z.ZodObject<{
+                textCharacters: z.ZodNumber;
+                blockCount: z.ZodNumber;
+                textBlockCount: z.ZodNumber;
+                mediaBlockCount: z.ZodNumber;
+                sourceEvidenceCount: z.ZodNumber;
+                citationCount: z.ZodNumber;
+                citedBlockCount: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+        reviewRef: z.ZodNullable<z.ZodString>;
+        reviewDecision: z.ZodNullable<z.ZodEnum<{
+            PASS: "PASS";
+            REWORK: "REWORK";
+            REJECT: "REJECT";
+        }>>;
+        support: z.ZodNullable<z.ZodObject<{
+            action: z.ZodEnum<{
+                ALLOW: "ALLOW";
+                REVIEW_REQUIRED: "REVIEW_REQUIRED";
+                DENY: "DENY";
+            }>;
+            reasonCodes: z.ZodArray<z.ZodString>;
+            missingEvidenceRefs: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+        governedPolicyReady: z.ZodBoolean;
+        consumerReadDecision: z.ZodNullable<z.ZodObject<{
+            action: z.ZodEnum<{
+                ALLOW: "ALLOW";
+                REVIEW_REQUIRED: "REVIEW_REQUIRED";
+                DENY: "DENY";
+            }>;
+            reasonCodes: z.ZodArray<z.ZodString>;
+            authority: z.ZodEnum<{
+                AUTHENTICATED_READER: "AUTHENTICATED_READER";
+                LOCAL_PROFILE_SIMULATION: "LOCAL_PROFILE_SIMULATION";
+            }>;
+        }, z.core.$strict>>;
+        externalReady: z.ZodBoolean;
+        successorRef: z.ZodNullable<z.ZodString>;
+        blockers: z.ZodArray<z.ZodString>;
+        nextActions: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            tool: z.ZodNullable<z.ZodString>;
+            arguments: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+            requiredScopes: z.ZodArray<z.ZodString>;
+            missingScopes: z.ZodArray<z.ZodString>;
+            missingFields: z.ZodArray<z.ZodString>;
+            canExecute: z.ZodBoolean;
+            automatic: z.ZodBoolean;
+            reasonCode: z.ZodString;
+            cli: z.ZodObject<{
+                command: z.ZodString;
+                flags: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+            }, z.core.$strict>;
+            http: z.ZodObject<{
+                method: z.ZodLiteral<"POST">;
+                path: z.ZodLiteral<"/mcp/management">;
+                tool: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const workflowErrorSchema: z.ZodObject<{
+    errorCode: z.ZodString;
+    completedPhase: z.ZodOptional<z.ZodEnum<{
+        REGISTERED: "REGISTERED";
+        VALIDATED: "VALIDATED";
+        PERSISTED: "PERSISTED";
+        CATALOG_PROJECTED: "CATALOG_PROJECTED";
+    }>>;
+    ref: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const workflowToolInputSchemas: {
+    readonly knowledge_workflow_guide: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+        projectRef: z.ZodString;
+    }, z.core.$strict>>;
+    readonly knowledge_workflow_plan: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+        projectRef: z.ZodString;
+        ref: z.ZodString;
+    }, z.core.$strict>>;
+    readonly knowledge_workflow_advance: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+        projectRef: z.ZodString;
+        ref: z.ZodString;
+        action: z.ZodEnum<{
+            SUBMIT_REVIEW: "SUBMIT_REVIEW";
+            FINALIZE_REVIEW: "FINALIZE_REVIEW";
+            PREPARE_SOURCE: "PREPARE_SOURCE";
+            REGISTER: "REGISTER";
+        }>;
+        expectedVersion: z.ZodOptional<z.ZodNumber>;
+        actedAt: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strict>>;
+    readonly knowledge_agent_submit: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+        projectRef: z.ZodString;
+        sourceId: z.ZodString;
+        contentBase64: z.ZodString;
+        mediaType: z.ZodString;
+        access: z.ZodDefault<z.ZodEnum<{
+            PUBLIC: "PUBLIC";
+            TENANT: "TENANT";
+            INTERNAL: "INTERNAL";
+            FDE_INTERNAL: "FDE_INTERNAL";
+        }>>;
+        submittedAt: z.ZodOptional<z.ZodISODateTime>;
+        freshnessSeconds: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+};
+export declare const workflowToolScopes: {
+    readonly knowledge_workflow_guide: "knowledge.workflow.read";
+    readonly knowledge_workflow_plan: "knowledge.workflow.read";
+    readonly knowledge_workflow_advance: "knowledge.workflow.read";
+    readonly knowledge_agent_submit: "knowledge.material.write";
+};
+export declare const workflowActionScopes: {
+    readonly PREPARE_SOURCE: "knowledge.compose";
+    readonly SUBMIT_REVIEW: "knowledge.compose";
+    readonly FINALIZE_REVIEW: "knowledge.approve";
+    readonly REGISTER: "knowledge.material.write";
+};
+export type WorkflowPlan = z.infer<typeof workflowPlanSchema>;
+export type WorkflowNextAction = z.infer<typeof workflowNextActionSchema>;
+export type WorkflowAction = z.infer<typeof workflowActionSchema>;
+export type WorkflowReadDecision = z.infer<typeof readDecision>;
+/** 网络成功和失败共享可发现 schema，阶段包含已经完成注册后的尾部失败。 */
+export declare const agentSubmitResultSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    production: z.ZodObject<{
+        phase: z.ZodEnum<{
+            REGISTERED: "REGISTERED";
+            CATALOG_PROJECTED: "CATALOG_PROJECTED";
+        }>;
+        ref: z.ZodString;
+        registered: z.ZodBoolean;
+        identity: z.ZodEnum<{
+            NOT_CONFIGURED: "NOT_CONFIGURED";
+            CONFIGURED: "CONFIGURED";
+        }>;
+    }, z.core.$strict>;
+    presentation: z.ZodNullable<z.ZodObject<{
+        documentRef: z.ZodString;
+        inserted: z.ZodBoolean;
+        contentHash: z.ZodString;
+    }, z.core.$strict>>;
+    evidenceRef: z.ZodString;
+    projectRef: z.ZodString;
+    contentHash: z.ZodString;
+    byteLength: z.ZodNumber;
+    inserted: z.ZodBoolean;
+    lifecycle: z.ZodLiteral<"QUEUED">;
+    contentClass: z.ZodLiteral<"RAW_EVIDENCE">;
+    nextStep: z.ZodObject<{
+        tool: z.ZodLiteral<"knowledge_workflow_plan">;
+        arguments: z.ZodObject<{
+            projectRef: z.ZodString;
+            ref: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const workflowToolOutputSchemas: {
+    readonly knowledge_workflow_guide: {
+        type: string;
+        oneOf: z.core.ZodStandardJSONSchemaPayload<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>[];
+    };
+    readonly knowledge_workflow_plan: {
+        type: string;
+        oneOf: z.core.ZodStandardJSONSchemaPayload<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>[];
+    };
+    readonly knowledge_workflow_advance: {
+        type: string;
+        oneOf: z.core.ZodStandardJSONSchemaPayload<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>[];
+    };
+    readonly knowledge_agent_submit: {
+        type: string;
+        oneOf: z.core.ZodStandardJSONSchemaPayload<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>[];
+    };
+};
+/** 同一份模型与参数 schema 供 CLI、MCP guide 和文档示例使用；不给 review 默认 PASS。 */
+export declare function workflowGuide(): {
+    schemaVersion: number;
+    model: {
+        raw: string;
+        reviewed: string;
+        lifecycle: string[];
+        publication: string[];
+    };
+    rules: string[];
+    tools: Record<string, {
+        requiredScope: string;
+        inputSchema: unknown;
+    }>;
+    advanceScopes: {
+        readonly PREPARE_SOURCE: "knowledge.compose";
+        readonly SUBMIT_REVIEW: "knowledge.compose";
+        readonly FINALIZE_REVIEW: "knowledge.approve";
+        readonly REGISTER: "knowledge.material.write";
+    };
+    https: {
+        method: string;
+        path: string;
+        body: {
+            tool: string;
+            arguments: string;
+        };
+        authorization: string;
+    };
+};
+export {};

package/dist/internal/serving-contracts/workflow.js

@@ -0,0 +1,37 @@
+/** Agent 的治理合同描述真实状态和下一步，不把写入权限解释为审核或正文权限。 */
+import { z } from 'zod';
+import { artifactStatusSchema, idSchema, isoDateTimeSchema, publicationReadinessReportSchema, sha256Schema, stableUriSchema } from '../contracts/index.js';
+import { consumerProjectRefSchema } from './consumer.js';
+import { managementToolInputSchemas } from './management.js';
+const project = z.object({ projectRef: consumerProjectRefSchema }).strict();
+export const workflowPlanInputSchema = project.extend({ ref: stableUriSchema }).strict();
+export const workflowGuideInputSchema = project;
+export const workflowActionSchema = z.enum(['PREPARE_SOURCE', 'SUBMIT_REVIEW', 'FINALIZE_REVIEW', 'REGISTER']);
+export const workflowAdvanceInputSchema = workflowPlanInputSchema.extend({ action: workflowActionSchema, expectedVersion: z.number().int().nonnegative().optional(), actedAt: isoDateTimeSchema.optional() }).strict().superRefine((value, ctx) => {
+    if (['SUBMIT_REVIEW', 'FINALIZE_REVIEW'].includes(value.action) && (!value.expectedVersion || !value.actedAt))
+        ctx.addIssue({ code: 'custom', message: 'transition requires exact expectedVersion and actedAt' });
+});
+export const agentSubmitInputSchema = project.extend({ sourceId: idSchema, contentBase64: z.string().min(1).max(87384), mediaType: z.string().trim().min(1).max(256), access: z.enum(['PUBLIC', 'TENANT', 'INTERNAL', 'FDE_INTERNAL']).default('TENANT'), submittedAt: isoDateTimeSchema.optional(), freshnessSeconds: z.number().int().min(60).max(86400).optional() }).strict();
+const argumentsSchema = z.record(z.string(), z.json());
+export const workflowNextActionSchema = z.object({ id: z.string(), tool: z.string().nullable(), arguments: argumentsSchema, requiredScopes: z.array(z.string()), missingScopes: z.array(z.string()), missingFields: z.array(z.string()), canExecute: z.boolean(), automatic: z.boolean(), reasonCode: z.string(), cli: z.object({ command: z.string(), flags: argumentsSchema }).strict(), http: z.object({ method: z.literal('POST'), path: z.literal('/mcp/management'), tool: z.string().nullable() }).strict() }).strict();
+const readDecision = z.object({ action: z.enum(['ALLOW', 'REVIEW_REQUIRED', 'DENY']), reasonCodes: z.array(z.string()), authority: z.enum(['AUTHENTICATED_READER', 'LOCAL_PROFILE_SIMULATION']) }).strict();
+export const workflowPlanSchema = z.object({ schemaVersion: z.literal(1), projectRef: consumerProjectRefSchema, ref: stableUriSchema, contentHash: sha256Schema, kind: z.string(), version: z.number().int().positive().nullable(), status: artifactStatusSchema.or(z.enum(['RAW_EVIDENCE', 'RAW_MATERIAL'])), productionPhase: z.enum(['PERSISTED', 'CATALOG_PROJECTED', 'REGISTERED']), rawMaterialAvailable: z.boolean().nullable(), readiness: publicationReadinessReportSchema.nullable(), reviewRef: stableUriSchema.nullable(), reviewDecision: z.enum(['PASS', 'REWORK', 'REJECT']).nullable(), support: z.object({ action: z.enum(['ALLOW', 'REVIEW_REQUIRED', 'DENY']), reasonCodes: z.array(z.string()), missingEvidenceRefs: z.array(stableUriSchema) }).strict().nullable(), governedPolicyReady: z.boolean(), consumerReadDecision: readDecision.nullable(), externalReady: z.boolean(), successorRef: stableUriSchema.nullable(), blockers: z.array(z.string()), nextActions: z.array(workflowNextActionSchema).max(70) }).strict();
+export const workflowAdvanceResultSchema = z.object({ schemaVersion: z.literal(1), action: workflowActionSchema, previousRef: stableUriSchema, inserted: z.boolean(), plan: workflowPlanSchema }).strict();
+export const workflowErrorSchema = z.object({ errorCode: z.string(), completedPhase: z.enum(['VALIDATED', 'PERSISTED', 'CATALOG_PROJECTED', 'REGISTERED']).optional(), ref: stableUriSchema.optional() }).strict();
+export const workflowToolInputSchemas = { knowledge_workflow_guide: z.toJSONSchema(workflowGuideInputSchema, { target: 'draft-07' }), knowledge_workflow_plan: z.toJSONSchema(workflowPlanInputSchema, { target: 'draft-07' }), knowledge_workflow_advance: z.toJSONSchema(workflowAdvanceInputSchema, { target: 'draft-07' }), knowledge_agent_submit: z.toJSONSchema(agentSubmitInputSchema, { target: 'draft-07' }) };
+export const workflowToolScopes = { knowledge_workflow_guide: 'knowledge.workflow.read', knowledge_workflow_plan: 'knowledge.workflow.read', knowledge_workflow_advance: 'knowledge.workflow.read', knowledge_agent_submit: 'knowledge.material.write' };
+export const workflowActionScopes = { PREPARE_SOURCE: 'knowledge.compose', SUBMIT_REVIEW: 'knowledge.compose', FINALIZE_REVIEW: 'knowledge.approve', REGISTER: 'knowledge.material.write' };
+/** 网络成功和失败共享可发现 schema，阶段包含已经完成注册后的尾部失败。 */
+export const agentSubmitResultSchema = z.object({ schemaVersion: z.literal(1), production: z.object({ phase: z.enum(['CATALOG_PROJECTED', 'REGISTERED']), ref: stableUriSchema, registered: z.boolean(), identity: z.enum(['CONFIGURED', 'NOT_CONFIGURED']) }).strict(), presentation: z.object({ documentRef: stableUriSchema, inserted: z.boolean(), contentHash: sha256Schema }).strict().nullable(), evidenceRef: stableUriSchema, projectRef: consumerProjectRefSchema, contentHash: sha256Schema, byteLength: z.number().int().min(1).max(65536), inserted: z.boolean(), lifecycle: z.literal('QUEUED'), contentClass: z.literal('RAW_EVIDENCE'), nextStep: z.object({ tool: z.literal('knowledge_workflow_plan'), arguments: workflowPlanInputSchema }).strict() }).strict();
+const guideSchema = z.object({ schemaVersion: z.literal(1), model: z.record(z.string(), z.json()), rules: z.array(z.string()), tools: z.record(z.string(), z.object({ requiredScope: z.string(), inputSchema: z.json() }).strict()), advanceScopes: z.record(z.string(), z.string()), https: z.json() }).strict();
+const output = (success) => ({ type: 'object', oneOf: [z.toJSONSchema(success, { target: 'draft-07' }), z.toJSONSchema(workflowErrorSchema, { target: 'draft-07' })] });
+export const workflowToolOutputSchemas = { knowledge_workflow_guide: output(guideSchema), knowledge_workflow_plan: output(workflowPlanSchema), knowledge_workflow_advance: output(workflowAdvanceResultSchema), knowledge_agent_submit: output(agentSubmitResultSchema) };
+/** 同一份模型与参数 schema 供 CLI、MCP guide 和文档示例使用；不给 review 默认 PASS。 */
+export function workflowGuide() {
+    const tools = {};
+    for (const [name, schema] of Object.entries(workflowToolInputSchemas))
+        tools[name] = { requiredScope: workflowToolScopes[name], inputSchema: schema };
+    for (const [name, schema] of Object.entries(managementToolInputSchemas))
+        tools[name] = { requiredScope: name === 'knowledge_review' ? 'knowledge.review' : name === 'knowledge_finalize_review' ? 'knowledge.approve' : 'knowledge.compose', inputSchema: schema };
+    return { schemaVersion: 1, model: { raw: 'Evidence / Material 保留原字节和 provenance；原文可读不等于结论已审核。', reviewed: 'KNOWLEDGE / INSIGHT', lifecycle: ['DRAFT', 'READY_FOR_REVIEW', 'REVIEW(PASS|REWORK|REJECT)', 'APPROVED|REWORK_REQUIRED|REJECTED'], publication: ['PERSISTED', 'CATALOG_PROJECTED', 'REGISTERED', 'consumer read ALLOW'] }, rules: ['先调用 knowledge_workflow_plan，再执行 canExecute 动作；缺字段由 Agent 补齐并重新计划。', '读取原文、核对引用和适用范围后，获授权 reviewer 显式写 PASS / REWORK / REJECT；不根据写入成功推断 PASS。', 'RESEARCH 先正式合成为 KNOWLEDGE / INSIGHT；Claim Currentness proposal 使用专门审核链。', 'freshnessSeconds 仅为作者在系统内首次保存的精确快照时效，不证明外部网页已复核；同身份重放不延长时效。', 'externalReady 需要注册、治理门通过及当前已鉴权消费者实际 read ALLOW；CLI profile 是模拟。', 'Plan 不提供正文或 Review summary；审核时使用独立 read scope 读取 exact ref。'], tools, advanceScopes: workflowActionScopes, https: { method: 'POST', path: '/mcp/management', body: { tool: 'tool name', arguments: '对应 inputSchema' }, authorization: 'OAuth Bearer + client/project binding；API key 不授予管理权限' } };
+}

package/dist/material-stream.d.ts

@@ -0,0 +1,18 @@
+export interface MaterialStreamOptions {
+    range?: string;
+    head?: boolean;
+    signal?: AbortSignal;
+    expectedContentHash?: string;
+}
+export interface MaterialStreamResponse {
+    status: 200 | 206;
+    contentClass: string;
+    contentHash: string;
+    mediaType: string;
+    contentLength: number;
+    contentRange: string | null;
+    body: ReadableStream<Uint8Array> | null;
+    verification: 'SERVER_VERIFIED_BEFORE_HEADERS';
+}
+/** Streaming does not buffer large payloads; the whole-object hash is not a hash of a Range segment. */
+export declare function materialStream(fetchImpl: typeof fetch, url: URL, token: string, options: MaterialStreamOptions): Promise<MaterialStreamResponse>;

package/dist/material-stream.js

@@ -0,0 +1,29 @@
+/** Streaming does not buffer large payloads; the whole-object hash is not a hash of a Range segment. */
+export async function materialStream(fetchImpl, url, token, options) {
+    const requested = options.range ? /^bytes=(\d*)-(\d*)$/.exec(options.range) : null;
+    if (options.range && (!requested || !requested[1] && !requested[2] || requested.slice(1).some(part => part !== '' && !Number.isSafeInteger(Number(part))) || !requested[1] && Number(requested[2]) === 0))
+        throw new Error('MATERIAL_STREAM_RANGE_INVALID');
+    const response = await fetchImpl(url, { method: options.head ? 'HEAD' : 'GET', headers: { authorization: `Bearer ${token}`, accept: 'application/octet-stream', ...(options.range ? { range: options.range } : {}) }, redirect: 'error', ...(options.signal ? { signal: options.signal } : {}) });
+    const fail = async (code) => { await response.body?.cancel(); throw new Error(code); };
+    if (response.status !== 200 && response.status !== 206)
+        return fail(`MATERIAL_STREAM_HTTP_${response.status}`);
+    const contentClass = response.headers.get('x-knowledge-content-class');
+    if (!contentClass || !['ARTIFACT_SNAPSHOT', 'RAW_EVIDENCE', 'RAW_EVIDENCE_MEDIA', 'REFERENCE_SNAPSHOT', 'REGISTERED_MATERIAL'].includes(contentClass))
+        return fail('MATERIAL_STREAM_CLASS_INVALID');
+    const hash = response.headers.get('x-knowledge-content-hash'), type = response.headers.get('content-type'), rawLength = response.headers.get('content-length'), contentRange = response.headers.get('content-range');
+    if (response.headers.get('x-knowledge-serving-action') !== 'ALLOW' || !hash || !/^sha256:[a-f0-9]{64}$/.test(hash) || !type || rawLength === null || !/^\d+$/.test(rawLength) || !Number.isSafeInteger(Number(rawLength)))
+        return fail('MATERIAL_STREAM_DESCRIPTOR_INVALID');
+    if (options.expectedContentHash && hash !== options.expectedContentHash)
+        return fail('MATERIAL_STREAM_IDENTITY_MISMATCH');
+    if (response.status === 206) {
+        const parts = /^bytes (\d+)-(\d+)\/(\d+)$/.exec(contentRange ?? '');
+        if (!requested || !parts || parts.slice(1).some(part => !Number.isSafeInteger(Number(part))) || Number(parts[1]) > Number(parts[2]) || Number(parts[2]) - Number(parts[1]) + 1 !== Number(rawLength) || Number(parts[2]) >= Number(parts[3]))
+            return fail('MATERIAL_STREAM_RANGE_RESPONSE_INVALID');
+        const total = Number(parts[3]), start = requested[1] ? Number(requested[1]) : Math.max(0, total - Number(requested[2])), end = requested[1] && requested[2] ? Math.min(total - 1, Number(requested[2])) : total - 1;
+        if (start !== Number(parts[1]) || end !== Number(parts[2]))
+            return fail('MATERIAL_STREAM_RANGE_RESPONSE_INVALID');
+    }
+    if (!options.head && !response.body && Number(rawLength) > 0)
+        return fail('MATERIAL_STREAM_BODY_MISSING');
+    return { status: response.status, contentClass, contentHash: hash, mediaType: type, contentLength: Number(rawLength), contentRange, body: response.body, verification: 'SERVER_VERIFIED_BEFORE_HEADERS' };
+}