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

package/dist/internal/contracts/currentness.js

@@ -0,0 +1,221 @@
+import { z } from 'zod';
+import { isoDateTimeSchema, projectKeySchema, schemaVersionSchema, stableUriSchema } from './common.js';
+export const currentnessStateSchema = z.enum(['CURRENT', 'DUE', 'STALE', 'BLOCKED', 'UNKNOWN']);
+export const currentnessActionSchema = z.enum(['ALLOW', 'REVIEW_REQUIRED', 'DENY']);
+export const currentnessSubjectKindSchema = z.enum(['SOURCE', 'EVIDENCE', 'ARTIFACT']);
+export const currentnessPolicySchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    dueAfterSeconds: z.number().int().min(60).max(366 * 24 * 60 * 60),
+    staleAfterSeconds: z.number().int().min(60).max(5 * 366 * 24 * 60 * 60),
+    staleAction: currentnessActionSchema.default('REVIEW_REQUIRED'),
+    unknownAction: currentnessActionSchema.default('REVIEW_REQUIRED'),
+    blockedAction: currentnessActionSchema.default('REVIEW_REQUIRED'),
+}).strict().superRefine((value, ctx) => {
+    if (value.staleAfterSeconds < value.dueAfterSeconds) {
+        ctx.addIssue({ code: 'custom', path: ['staleAfterSeconds'], message: 'staleAfterSeconds must be >= dueAfterSeconds' });
+    }
+});
+export const currentnessReasonCodeSchema = z.enum([
+    'CURRENT_WITHIN_CADENCE',
+    'REFRESH_DUE',
+    'STALE_AFTER_THRESHOLD',
+    'SOURCE_BLOCKED',
+    'SOURCE_CONTENT_CHANGED',
+    'NO_SUCCESSFUL_OBSERVATION',
+]);
+export const currentnessAssessmentSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    subjectRef: stableUriSchema,
+    subjectKind: currentnessSubjectKindSchema,
+    projectRef: stableUriSchema.optional(),
+    sourceRevisionRef: stableUriSchema.optional(),
+    basisRef: stableUriSchema.nullable().default(null),
+    state: currentnessStateSchema,
+    action: currentnessActionSchema,
+    assessedAt: isoDateTimeSchema,
+    observedAt: isoDateTimeSchema.nullable().default(null),
+    lastSuccessAt: isoDateTimeSchema.nullable().default(null),
+    lastAttemptAt: isoDateTimeSchema.nullable().default(null),
+    dueAt: isoDateTimeSchema.nullable().default(null),
+    staleAt: isoDateTimeSchema.nullable().default(null),
+    ageSeconds: z.number().int().nonnegative().nullable().default(null),
+    reasonCode: currentnessReasonCodeSchema,
+    policy: currentnessPolicySchema,
+}).strict();
+export const claimCurrentnessStatusSchema = z.enum([
+    'CURRENT',
+    'PARTIALLY_SUPERSEDED',
+    'SUPERSEDED',
+    'PENDING_CURRENTNESS_REVIEW',
+    'HISTORICAL_REFERENCE',
+    'DYNAMIC_CURRENT',
+    'DYNAMIC_EXPIRED',
+]);
+export const claimCurrentnessRiskSchema = z.enum(['STANDARD', 'HIGH']);
+export const claimTimeSensitivitySchema = z.enum(['DURABLE', 'TIME_SENSITIVE', 'DYNAMIC']);
+export const claimReviewTriggerSchema = z.enum([
+    'SCHEDULED_REFRESH',
+    'SAME_URL_DIFFERENT_HASH',
+    'LATER_OFFICIAL_SOURCE',
+    'REGULATORY_ACTION',
+    'OPERATOR_TRANSITION',
+    'CORRECTION',
+    'DYNAMIC_EXPIRY',
+    'INITIAL_REVIEW',
+]);
+const evidenceUriSchema = stableUriSchema.refine((value) => value.toLowerCase().startsWith('evidence://'), 'claim provenance must use EvidenceRef');
+const claimIdSchema = z.string().trim().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+export const claimCurrentnessChangeSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    artifactRef: stableUriSchema,
+    claimId: claimIdSchema,
+    scope: z.string().trim().min(1).max(1000),
+    status: claimCurrentnessStatusSchema,
+    risk: claimCurrentnessRiskSchema.default('STANDARD'),
+    timeSensitivity: claimTimeSensitivitySchema.default('DURABLE'),
+    effectiveFrom: isoDateTimeSchema.nullable().default(null),
+    effectiveUntil: isoDateTimeSchema.nullable().default(null),
+    discoveredAt: isoDateTimeSchema,
+    reviewTrigger: claimReviewTriggerSchema,
+    previousEvidenceRefs: z.array(evidenceUriSchema).max(64).default([]),
+    currentEvidenceRefs: z.array(evidenceUriSchema).max(64).default([]),
+    replacementArtifactRef: stableUriSchema.nullable().default(null),
+    reason: z.string().trim().min(1).max(4000),
+}).strict().superRefine((value, ctx) => {
+    const prior = new Set(value.previousEvidenceRefs);
+    const current = new Set(value.currentEvidenceRefs);
+    if (prior.size !== value.previousEvidenceRefs.length)
+        ctx.addIssue({ code: 'custom', path: ['previousEvidenceRefs'], message: 'duplicate previous EvidenceRef' });
+    if (current.size !== value.currentEvidenceRefs.length)
+        ctx.addIssue({ code: 'custom', path: ['currentEvidenceRefs'], message: 'duplicate current EvidenceRef' });
+    if ([...prior].some((ref) => current.has(ref)))
+        ctx.addIssue({ code: 'custom', path: ['currentEvidenceRefs'], message: 'previous and current EvidenceRefs must be distinct' });
+    if (value.effectiveFrom && value.effectiveUntil && Date.parse(value.effectiveUntil) <= Date.parse(value.effectiveFrom)) {
+        ctx.addIssue({ code: 'custom', path: ['effectiveUntil'], message: 'effectiveUntil must be later than effectiveFrom' });
+    }
+    if (value.timeSensitivity === 'TIME_SENSITIVE' && value.status !== 'PENDING_CURRENTNESS_REVIEW' && !value.effectiveFrom) {
+        ctx.addIssue({ code: 'custom', path: ['effectiveFrom'], message: 'time-sensitive reviewed claims require source-grounded effectiveFrom' });
+    }
+    if (value.timeSensitivity === 'DYNAMIC' && !value.effectiveUntil) {
+        ctx.addIssue({ code: 'custom', path: ['effectiveUntil'], message: 'dynamic claims require an explicit expiry boundary' });
+    }
+    if (value.status === 'DYNAMIC_CURRENT' && value.effectiveUntil && Date.parse(value.effectiveUntil) <= Date.parse(value.discoveredAt)) {
+        ctx.addIssue({ code: 'custom', path: ['effectiveUntil'], message: 'dynamic current claim must still be valid when discovered' });
+    }
+    if (value.status === 'DYNAMIC_EXPIRED' && value.effectiveUntil && Date.parse(value.discoveredAt) < Date.parse(value.effectiveUntil)) {
+        ctx.addIssue({ code: 'custom', path: ['effectiveUntil'], message: 'dynamic expired claim requires discovery at or after expiry' });
+    }
+    if (['CURRENT', 'DYNAMIC_CURRENT'].includes(value.status) && value.currentEvidenceRefs.length === 0) {
+        ctx.addIssue({ code: 'custom', path: ['currentEvidenceRefs'], message: 'current claim requires exact current EvidenceRef' });
+    }
+    if (['PARTIALLY_SUPERSEDED', 'SUPERSEDED'].includes(value.status)) {
+        if (value.previousEvidenceRefs.length === 0)
+            ctx.addIssue({ code: 'custom', path: ['previousEvidenceRefs'], message: 'supersession requires previous EvidenceRef' });
+        if (value.currentEvidenceRefs.length === 0)
+            ctx.addIssue({ code: 'custom', path: ['currentEvidenceRefs'], message: 'supersession requires replacement/current EvidenceRef' });
+    }
+    if (['HISTORICAL_REFERENCE', 'DYNAMIC_EXPIRED'].includes(value.status) && value.previousEvidenceRefs.length === 0) {
+        ctx.addIssue({ code: 'custom', path: ['previousEvidenceRefs'], message: 'historical/expired claim requires retained prior EvidenceRef' });
+    }
+    if (value.status === 'PENDING_CURRENTNESS_REVIEW' && value.previousEvidenceRefs.length === 0 && value.currentEvidenceRefs.length === 0) {
+        ctx.addIssue({ code: 'custom', path: ['currentEvidenceRefs'], message: 'pending currentness review requires at least one exact EvidenceRef' });
+    }
+});
+export const claimCurrentnessDecisionSchema = claimCurrentnessChangeSchema.safeExtend({
+    reviewedAt: isoDateTimeSchema,
+}).superRefine((value, ctx) => {
+    if (Date.parse(value.reviewedAt) < Date.parse(value.discoveredAt)) {
+        ctx.addIssue({ code: 'custom', path: ['reviewedAt'], message: 'reviewedAt must not precede discoveredAt' });
+    }
+    if (value.status === 'DYNAMIC_CURRENT' && value.effectiveUntil && Date.parse(value.reviewedAt) >= Date.parse(value.effectiveUntil)) {
+        ctx.addIssue({ code: 'custom', path: ['effectiveUntil'], message: 'dynamic current claim must not already be expired at review time' });
+    }
+});
+export const claimCurrentnessProposalSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    type: z.literal('CLAIM_CURRENTNESS_PROPOSAL'),
+    projectKey: projectKeySchema,
+    proposalId: z.string().trim().min(3).max(80).regex(/^[a-z0-9][a-z0-9._-]*$/),
+    artifactRef: stableUriSchema,
+    createdAt: isoDateTimeSchema,
+    changes: z.array(claimCurrentnessChangeSchema).min(1).max(256),
+}).strict().superRefine((value, ctx) => {
+    const ids = new Set();
+    value.changes.forEach((change, index) => {
+        if (change.artifactRef !== value.artifactRef)
+            ctx.addIssue({ code: 'custom', path: ['changes', index, 'artifactRef'], message: 'claim change artifactRef must match proposal artifactRef' });
+        if (ids.has(change.claimId))
+            ctx.addIssue({ code: 'custom', path: ['changes', index, 'claimId'], message: 'duplicate claimId in proposal' });
+        ids.add(change.claimId);
+        if (Date.parse(change.discoveredAt) > Date.parse(value.createdAt))
+            ctx.addIssue({ code: 'custom', path: ['changes', index, 'discoveredAt'], message: 'discoveredAt must not be after proposal createdAt' });
+    });
+});
+export const claimCurrentnessLedgerSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    ledgerId: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    projectKey: projectKeySchema,
+    artifactRef: stableUriSchema,
+    proposalRef: stableUriSchema,
+    reviewRef: stableUriSchema,
+    reviewedAt: isoDateTimeSchema,
+    decisionsHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    decisions: z.array(claimCurrentnessDecisionSchema).min(1).max(256),
+}).strict().superRefine((value, ctx) => {
+    const ids = new Set();
+    value.decisions.forEach((decision, index) => {
+        if (decision.artifactRef !== value.artifactRef)
+            ctx.addIssue({ code: 'custom', path: ['decisions', index, 'artifactRef'], message: 'decision artifactRef must match ledger artifactRef' });
+        if (decision.reviewedAt !== value.reviewedAt)
+            ctx.addIssue({ code: 'custom', path: ['decisions', index, 'reviewedAt'], message: 'decision reviewedAt must match ledger review' });
+        if (ids.has(decision.claimId))
+            ctx.addIssue({ code: 'custom', path: ['decisions', index, 'claimId'], message: 'duplicate claimId in ledger' });
+        ids.add(decision.claimId);
+    });
+});
+export const artifactSemanticStatusSchema = z.enum(['REVIEWED', 'SUPERSEDED']);
+export const artifactSupportStateSchema = z.enum([
+    'CURRENTLY_SUPPORTED',
+    'REFRESH_DUE',
+    'CURRENTNESS_REVIEW_REQUIRED',
+    'CURRENTNESS_DENIED',
+    'SUPERSEDED',
+]);
+export const artifactSupportEvidenceSchema = z.object({
+    evidenceRef: stableUriSchema,
+    state: currentnessStateSchema,
+    action: currentnessActionSchema,
+    assessedAt: isoDateTimeSchema,
+    lastSuccessAt: isoDateTimeSchema.nullable(),
+    reasonCode: currentnessReasonCodeSchema,
+}).strict();
+export const artifactSupportAssessmentSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    artifactRef: stableUriSchema,
+    identityRef: stableUriSchema,
+    projectKey: projectKeySchema,
+    artifactKind: z.enum(['KNOWLEDGE', 'INSIGHT']),
+    semanticStatus: artifactSemanticStatusSchema,
+    supportState: artifactSupportStateSchema,
+    action: currentnessActionSchema,
+    assessedAt: isoDateTimeSchema,
+    validUntil: isoDateTimeSchema.nullable(),
+    evidence: z.array(artifactSupportEvidenceSchema).max(256),
+    claims: z.array(claimCurrentnessDecisionSchema).max(256).default([]),
+    missingEvidenceRefs: z.array(stableUriSchema).max(256),
+    reasonCodes: z.array(z.enum([
+        'ALL_EVIDENCE_CURRENT',
+        'EVIDENCE_REFRESH_DUE',
+        'EVIDENCE_REVIEW_REQUIRED',
+        'EVIDENCE_DENIED',
+        'EVIDENCE_CURRENTNESS_MISSING',
+        'ARTIFACT_EVIDENCE_REQUIRED',
+        'ARTIFACT_VALIDITY_EXPIRED',
+        'ARTIFACT_EXPLICITLY_SUPERSEDED',
+        'CLAIM_PARTIALLY_SUPERSEDED',
+        'CLAIM_PENDING_CURRENTNESS_REVIEW',
+        'CLAIM_SUPERSEDED',
+        'CLAIM_HISTORICAL_REFERENCE',
+        'CLAIM_DYNAMIC_EXPIRED',
+    ])).min(1).max(32),
+}).strict();

package/dist/internal/contracts/event.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema, } from './common.js';
+export const knowledgeEventTypeSchema = z.enum([
+    'SOURCE_CHANGED',
+    'SOURCE_FAILURE',
+    'REVIEW_READY',
+    'APPROVAL_READY',
+    'MATERIAL_DRIFT',
+    'BOUNDARY_RISK',
+    'CURRENTNESS_RISK',
+    'CLOSURE_MILESTONE',
+    'SCHEDULER_FAILURE',
+    'SIGNAL_READY',
+    'GAP_READY',
+    'PROGRAM_EVOLUTION_READY',
+]);
+export const eventSeveritySchema = z.enum(['INFO', 'NORMAL', 'WARNING', 'CRITICAL']);
+export const knowledgeEventSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    eventId: idSchema,
+    projectKey: projectKeySchema.optional(),
+    projectRef: stableUriSchema.optional(),
+    sourceRef: stableUriSchema.optional(),
+    sourceRevisionRef: stableUriSchema.optional(),
+    collectionBatchRef: stableUriSchema.optional(),
+    type: knowledgeEventTypeSchema,
+    severity: eventSeveritySchema,
+    createdAt: isoDateTimeSchema,
+    runtimeNodeId: idSchema.optional(),
+    artifactRef: stableUriSchema.optional(),
+    evidenceRefs: z.array(stableUriSchema).max(256).default([]),
+    contentHash: sha256Schema.optional(),
+    requiresUserAction: z.boolean(),
+    dedupeKey: z.string().trim().min(1).max(512),
+}).strict();

package/dist/internal/contracts/evidence.js

@@ -0,0 +1,171 @@
+import { z } from 'zod';
+import { accessClassificationSchema, idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema, } from './common.js';
+export const evidenceModalitySchema = z.enum(['TEXT', 'PDF', 'IMAGE', 'AUDIO', 'VIDEO', 'BINARY']);
+export const evidenceReviewModeSchema = z.enum(['TEXT_NATIVE', 'MULTIMODAL_NATIVE', 'EXTERNAL_EXTRACTOR_REQUIRED']);
+export const evidenceReviewInstructionSchema = z.enum([
+    'READ_ORIGINAL_TEXT',
+    'INSPECT_ORIGINAL_DOCUMENT',
+    'INSPECT_ORIGINAL_IMAGE',
+    'LISTEN_TO_ORIGINAL_AUDIO',
+    'INSPECT_ORIGINAL_VIDEO',
+    'USE_APPROVED_EXTERNAL_EXTRACTOR',
+]);
+const pageRangeSchema = z.object({
+    startPage: z.number().int().positive(),
+    endPage: z.number().int().positive(),
+}).strict().superRefine((value, ctx) => {
+    if (value.endPage < value.startPage)
+        ctx.addIssue({ code: 'custom', path: ['endPage'], message: 'endPage must be >= startPage' });
+});
+const timeRangeSchema = z.object({
+    startMs: z.number().int().nonnegative(),
+    endMs: z.number().int().nonnegative(),
+}).strict().superRefine((value, ctx) => {
+    if (value.endMs < value.startMs)
+        ctx.addIssue({ code: 'custom', path: ['endMs'], message: 'endMs must be >= startMs' });
+});
+export const evidenceReviewHintsSchema = z.object({
+    pageRanges: z.array(pageRangeSchema).max(64).default([]),
+    timeRanges: z.array(timeRangeSchema).max(64).default([]),
+    frameTimestampsMs: z.array(z.number().int().nonnegative()).max(64).default([]),
+}).strict();
+export const evidenceReviewAttachmentSchema = z.object({
+    evidenceRef: stableUriSchema,
+    contentHash: sha256Schema,
+    mediaType: z.string().trim().min(1).max(256),
+    byteLength: z.number().int().nonnegative().nullable(),
+    modality: evidenceModalitySchema,
+    reviewMode: evidenceReviewModeSchema,
+    instruction: evidenceReviewInstructionSchema,
+    rawBytesEmbedded: z.literal(false),
+    materializationRequired: z.literal(true),
+    reviewHints: evidenceReviewHintsSchema.optional(),
+}).strict().superRefine((value, ctx) => {
+    const expected = value.modality === 'TEXT' ? ['TEXT_NATIVE', 'READ_ORIGINAL_TEXT']
+        : value.modality === 'PDF' ? ['MULTIMODAL_NATIVE', 'INSPECT_ORIGINAL_DOCUMENT']
+            : value.modality === 'IMAGE' ? ['MULTIMODAL_NATIVE', 'INSPECT_ORIGINAL_IMAGE']
+                : value.modality === 'AUDIO' ? ['MULTIMODAL_NATIVE', 'LISTEN_TO_ORIGINAL_AUDIO']
+                    : value.modality === 'VIDEO' ? ['MULTIMODAL_NATIVE', 'INSPECT_ORIGINAL_VIDEO']
+                        : ['EXTERNAL_EXTRACTOR_REQUIRED', 'USE_APPROVED_EXTERNAL_EXTRACTOR'];
+    if (value.reviewMode !== expected[0])
+        ctx.addIssue({ code: 'custom', path: ['reviewMode'], message: `reviewMode must be ${expected[0]} for ${value.modality}` });
+    if (value.instruction !== expected[1])
+        ctx.addIssue({ code: 'custom', path: ['instruction'], message: `instruction must be ${expected[1]} for ${value.modality}` });
+    const hints = value.reviewHints;
+    if (hints?.pageRanges.length && value.modality !== 'PDF')
+        ctx.addIssue({ code: 'custom', path: ['reviewHints', 'pageRanges'], message: 'pageRanges require PDF modality' });
+    if (hints?.timeRanges.length && !['AUDIO', 'VIDEO'].includes(value.modality))
+        ctx.addIssue({ code: 'custom', path: ['reviewHints', 'timeRanges'], message: 'timeRanges require AUDIO or VIDEO modality' });
+    if (hints?.frameTimestampsMs.length && value.modality !== 'VIDEO')
+        ctx.addIssue({ code: 'custom', path: ['reviewHints', 'frameTimestampsMs'], message: 'frameTimestampsMs require VIDEO modality' });
+});
+export const evidenceMaterializationReceiptSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    evidenceRef: stableUriSchema,
+    contentHash: sha256Schema,
+    mediaType: z.string().trim().min(1).max(256),
+    byteLength: z.number().int().nonnegative(),
+    modality: evidenceModalitySchema,
+    reviewMode: evidenceReviewModeSchema,
+    instruction: evidenceReviewInstructionSchema,
+    reviewHints: evidenceReviewHintsSchema.optional(),
+    access: accessClassificationSchema,
+    runtimeNodeId: idSchema,
+    materializedAt: isoDateTimeSchema,
+    runtimeLocalPath: z.string().trim().min(1).max(4096).startsWith('/'),
+    reused: z.boolean(),
+}).strict();
+export const collectorIdentitySchema = z.object({
+    collectorId: idSchema,
+    version: z.string().trim().min(1).max(128),
+}).strict();
+/** 附属媒体沿用 Source 身份，但不能替代该 Source 的主文档。 */
+export const RICH_MEDIA_COLLECTOR_ID = 'knowledge-v2.rich-document-media';
+// 中文职责：保存只读 POST 的请求体对象索引，响应 contentHash 始终代表原始响应。
+export const evidenceRequestSchema = z.object({
+    schemaVersion: z.literal(1), method: z.literal('POST'),
+    bodyContentHash: sha256Schema, bodyMediaType: z.literal('application/x-www-form-urlencoded'),
+    bodyByteLength: z.number().int().nonnegative().max(16 * 1024),
+}).strict();
+export const evidenceRefSchema = z.object({
+    // Re-admission preserves acquisition facts; this link records reuse rather than a new download.
+    recoveryProvenance: z.object({ mode: z.literal('REUSED_PRIOR_EVIDENCE'), originEvidenceRef: stableUriSchema, originProjectRef: stableUriSchema, originSourceRevisionRef: stableUriSchema, originRuntimeNodeId: idSchema, handoffReceiptRef: stableUriSchema }).strict().optional(),
+    request: evidenceRequestSchema.optional(),
+    schemaVersion: schemaVersionSchema,
+    evidenceId: idSchema,
+    sourceId: idSchema,
+    sourceIds: z.array(idSchema).min(1).max(64).optional(),
+    projectKey: projectKeySchema.optional(),
+    projectRef: stableUriSchema.optional(),
+    collector: collectorIdentitySchema,
+    contentHash: sha256Schema,
+    observedAt: isoDateTimeSchema,
+    runtimeNodeId: idSchema,
+    access: accessClassificationSchema,
+    canonicalUri: stableUriSchema.optional(),
+    mediaType: z.string().trim().min(1).max(256).optional(),
+    byteLength: z.number().int().nonnegative().optional(),
+    sourceSetRef: stableUriSchema.optional(),
+    sourceItemId: idSchema.optional(),
+    sourceRevisionRef: stableUriSchema.optional(),
+    collectionBatchRef: stableUriSchema.optional(),
+    collectionTaskId: idSchema.optional(),
+    reviewHints: evidenceReviewHintsSchema.optional(),
+}).strict().superRefine((value, ctx) => {
+    if (value.recoveryProvenance) {
+        const origin = value.recoveryProvenance;
+        if (value.access !== 'PUBLIC')
+            ctx.addIssue({ code: 'custom', path: ['recoveryProvenance'], message: 'Recovery re-admission requires PUBLIC evidence' });
+        for (const [key, protocol] of [['originEvidenceRef', 'evidence:'], ['originProjectRef', 'knowledge-project:'], ['originSourceRevisionRef', 'project-source:'], ['handoffReceiptRef', 'runtime-handoff:']]) {
+            const url = new URL(origin[key]);
+            if (url.protocol !== protocol || url.hostname !== value.projectKey)
+                ctx.addIssue({ code: 'custom', path: ['recoveryProvenance', key], message: 'Recovery provenance must retain the same project and expected reference type' });
+        }
+        if (origin.originEvidenceRef === `evidence://${value.projectKey}/${encodeURIComponent(value.evidenceId)}`)
+            ctx.addIssue({ code: 'custom', path: ['recoveryProvenance'], message: 'Recovery origin cannot be self' });
+    }
+    if (Boolean(value.sourceSetRef) !== Boolean(value.sourceItemId))
+        ctx.addIssue({ code: 'custom', path: ['sourceSetRef'], message: 'sourceSetRef and sourceItemId must be provided together' });
+    if (Boolean(value.collectionBatchRef) !== Boolean(value.collectionTaskId))
+        ctx.addIssue({ code: 'custom', path: ['collectionBatchRef'], message: 'collectionBatchRef and collectionTaskId must be provided together' });
+    if (value.projectRef && value.projectKey) {
+        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 Evidence project' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['projectRef'], message: 'Invalid projectRef' });
+        }
+    }
+    if (value.sourceSetRef && value.projectKey) {
+        try {
+            const url = new URL(value.sourceSetRef);
+            if (url.protocol !== 'source-set:' || url.hostname.toLowerCase() !== value.projectKey.toLowerCase())
+                ctx.addIssue({ code: 'custom', path: ['sourceSetRef'], message: 'sourceSetRef project must match Evidence project' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['sourceSetRef'], message: 'Invalid sourceSetRef' });
+        }
+    }
+    if (value.sourceRevisionRef && value.projectKey) {
+        try {
+            const url = new URL(value.sourceRevisionRef);
+            if (url.protocol !== 'project-source:' || url.hostname.toLowerCase() !== value.projectKey.toLowerCase())
+                ctx.addIssue({ code: 'custom', path: ['sourceRevisionRef'], message: 'sourceRevisionRef project must match Evidence project' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['sourceRevisionRef'], message: 'Invalid sourceRevisionRef' });
+        }
+    }
+    if (value.collectionBatchRef && value.projectKey) {
+        try {
+            const url = new URL(value.collectionBatchRef);
+            if (url.protocol !== 'collection-batch:' || url.hostname.toLowerCase() !== value.projectKey.toLowerCase())
+                ctx.addIssue({ code: 'custom', path: ['collectionBatchRef'], message: 'collectionBatchRef project must match Evidence project' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['collectionBatchRef'], message: 'Invalid collectionBatchRef' });
+        }
+    }
+});

package/dist/internal/contracts/index.js

@@ -0,0 +1,55 @@
+export * from './common.js';
+export * from './source.js';
+export * from './evidence.js';
+export * from './observation.js';
+export * from './runtime.js';
+export * from './event.js';
+export * from './signal.js';
+export * from './artifact.js';
+export * from './review-packet.js';
+export * from './scheduler.js';
+export * from './currentness.js';
+export * from './projection.js';
+export * from './source-governance.js';
+export * from './review-plane.js';
+export * from './persistence.js';
+export * from './remote-file.js';
+export * from './project-intent.js';
+export * from './collection.js';
+export * from './collection-control.js';
+export * from './rich-document.js';
+export * from './material-carrier.js';
+export * from './reference-record.js';
+export * from './material-read.js';
+export * from './material-context.js';
+export * from './tenant-material-api.js';
+export * from './material-capability.js';
+export * from './public-reference.js';
+export * from './resource-scope.js';
+export * from './tenant-resource.js';
+export * from './tenant-resource-api.js';
+export * from './tenant-source.js';
+export * from './tenant-collection.js';
+export * from './tenant-collection-request.js';
+export * from './tenant-source-document.js';
+export * from './tenant-source-bridge.js';
+export * from './tenant-source-binding.js';
+export * from './tenant-source-cutover.js';
+export * from './tenant-rich-document.js';
+export * from './tenant-management.js';
+export * from './tenant-currentness.js';
+export * from './tenant-public-reference.js';
+export * from './tenant-project-control.js';
+export * from './tenant-budget.js';
+export * from './runtime-compatibility.js';
+export * from './tenant-web-collection.js';
+export * from './tenant-web-results.js';
+export * from './tenant-web-crawl.js';
+export * from './tenant-source-lease.js';
+export * from './tenant-web-dynamic.js';
+export * from './tenant-pdf-text.js';
+export * from './tenant-web-content-plan.js';
+export * from './tenant-web-content-result.js';
+export * from './tenant-web-content.js';
+export * from './tenant-web-workflow.js';
+export * from './resource-transfer.js';

package/dist/internal/contracts/material-capability.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import { rawRetrievalDecisionSchema, rawMaterialDirectoryItemSchema } from './material-read.js';
+import { sha256Schema } from './common.js';
+export const materialReadStateSchema = z.enum(['READY', 'UNSUPPORTED', 'MISSING', 'INTEGRITY_MISMATCH', 'DENIED']);
+export const materialCapabilitySchema = z.object({
+    item: rawMaterialDirectoryItemSchema, materialAccess: rawRetrievalDecisionSchema,
+    representation: z.object({ state: materialReadStateSchema, format: z.enum(['BYTES', 'JSON']), transfer: z.enum(['VERIFIED_STREAM', 'BUFFERED_JSON', 'UNSUPPORTED']), contentHash: sha256Schema.nullable(), mediaType: z.string().min(1).max(256), byteLength: z.number().int().nonnegative().safe().nullable(), methods: z.array(z.enum(['GET', 'HEAD'])).max(2), range: z.enum(['SINGLE', 'NONE']), verification: z.literal('ON_READ'), verificationChunkBytes: z.number().int().positive().nullable() }).strict(),
+}).strict();

package/dist/internal/contracts/material-carrier.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { accessClassificationSchema, isoDateTimeSchema, projectKeySchema, sha256Schema, stableUriSchema } from './common.js';
+export const materialResourceTypeSchema = z.string().regex(/^[a-z][a-z0-9._-]{0,63}$/);
+/** Provenance-bearing immutable metadata; original bytes live only in the shared CAS. */
+export const materialCarrierManifestSchema = z.object({
+    schemaVersion: z.literal(1), ref: stableUriSchema, projectKey: projectKeySchema, resourceType: materialResourceTypeSchema,
+    kind: z.string().min(1).max(128), access: accessClassificationSchema, title: z.string().max(512), summary: z.string().max(1024),
+    observedAt: isoDateTimeSchema, sourceRefs: z.array(stableUriSchema).min(1).max(128), sourceUri: stableUriSchema.nullable(), sourceSetRef: stableUriSchema.nullable().default(null),
+    storage: z.literal('CAS'), contentHash: sha256Schema, mediaType: z.string().min(1).max(256), byteLength: z.number().int().nonnegative().safe(),
+}).strict().superRefine((value, ctx) => { if (value.sourceSetRef && !value.sourceSetRef.startsWith(`source-set://${value.projectKey}/`))
+    ctx.addIssue({ code: 'custom', path: ['sourceSetRef'], message: 'Source Set must belong to the material source project' }); if (['artifact', 'evidence', 'reference', 'media'].includes(value.resourceType))
+    ctx.addIssue({ code: 'custom', path: ['resourceType'], message: 'built-in carriers retain their existing canonical stores' }); });
+export const materialRegistrationMetadataSchema = z.object({ ...materialCarrierManifestSchema.shape }).omit({ schemaVersion: true, contentHash: true, byteLength: true, storage: true });
+export const materialRegistrationRequestSchema = z.object({ projectRef: stableUriSchema, metadata: materialRegistrationMetadataSchema, contentBase64: z.string().max(87384) }).strict();
+export const materialRegistrationInputJsonSchema = z.toJSONSchema(materialRegistrationRequestSchema, { target: 'draft-07' });

package/dist/internal/contracts/material-context.js

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import { projectKeySchema, stableUriSchema } from './common.js';
+export const materialTenantIdSchema = z.string().min(1).max(256).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+export const materialContextSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('TENANT'), tenantId: materialTenantIdSchema, tenantRef: stableUriSchema }).strict(),
+    z.object({ type: z.literal('PROJECT'), tenantId: materialTenantIdSchema, projectKey: projectKeySchema, projectRef: stableUriSchema }).strict(),
+]);
+export const materialProjectScopeInputSchema = z.object({ mode: z.enum(['TENANT', 'EXPLICIT']).optional(), selectors: z.array(z.object({ type: z.enum(['SOURCE_PROJECT', 'REF']), value: z.string().min(1).max(4096), enabled: z.boolean() }).strict()).max(100).default([]) }).strict().superRefine((value, ctx) => { if (!value.mode && !value.selectors.length)
+    ctx.addIssue({ code: 'custom', message: 'An explicit scope mutation is required' }); });

package/dist/internal/contracts/material-read.js

@@ -0,0 +1,12 @@
+/** Retrieval permissions and immutable descriptors, independent of business usage decisions. */
+import { z } from 'zod';
+import { accessClassificationSchema, idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema } from './common.js';
+import { materialResourceTypeSchema } from './material-carrier.js';
+export const rawRetrievalProblemSchema = z.enum(['NOT_FOUND', 'CONTENT_ACCESS_DENIED', 'INTEGRITY_MISMATCH', 'UNAVAILABLE', 'UNSUPPORTED_RESOURCE']);
+export const rawRetrievalDecisionSchema = z.object({ schemaVersion: schemaVersionSchema, action: z.enum(['ALLOW', 'DENY']), reasonCodes: z.array(rawRetrievalProblemSchema).max(32), assessedAt: isoDateTimeSchema }).strict().superRefine((value, ctx) => { if ((value.action === 'ALLOW') !== (value.reasonCodes.length === 0))
+    ctx.addIssue({ code: 'custom', path: ['reasonCodes'], message: 'Retrieval decision and reasons must agree' }); });
+export const rawContentDescriptorSchema = z.object({ contentHash: sha256Schema, mediaType: z.string().trim().min(1).max(256), byteLength: z.number().int().nonnegative().safe() }).strict();
+export const rawArtifactSummarySchema = z.object({ ref: stableUriSchema, identityRef: stableUriSchema, projectKey: projectKeySchema, projectRef: stableUriSchema.nullable().default(null), artifactId: idSchema, kind: z.string().trim().min(1).max(128), version: z.number().int().positive(), status: z.string().trim().min(1).max(128), access: accessClassificationSchema, title: z.string().max(500).nullable(), createdAt: isoDateTimeSchema, observedAt: isoDateTimeSchema.nullable(), validUntil: isoDateTimeSchema.nullable(), content: rawContentDescriptorSchema }).strict();
+export const rawArtifactDetailSchema = rawArtifactSummarySchema.extend({ evidenceRefs: z.array(stableUriSchema).max(256), relatedRefs: z.array(stableUriSchema).max(256), supersedesRef: stableUriSchema.nullable() }).strict();
+export const rawEvidenceSummarySchema = z.object({ evidenceRef: stableUriSchema, projectKey: projectKeySchema, sourceId: idSchema, contentHash: sha256Schema, observedAt: isoDateTimeSchema, access: accessClassificationSchema, canonicalUri: stableUriSchema.nullable(), mediaType: z.string().max(256).nullable(), byteLength: z.number().int().nonnegative().safe().nullable(), projectRef: stableUriSchema.nullable().default(null), sourceSetRef: stableUriSchema.nullable(), sourceItemId: idSchema.nullable(), sourceRevisionRef: stableUriSchema.nullable().default(null), collectionBatchRef: stableUriSchema.nullable().default(null), collectionTaskId: idSchema.nullable().default(null) }).strict();
+export const rawMaterialDirectoryItemSchema = z.object({ ref: stableUriSchema, resourceType: materialResourceTypeSchema, sourceProjectKey: projectKeySchema, identityHash: sha256Schema, kind: z.string().min(1).max(128), classification: accessClassificationSchema, mediaType: z.string().min(1).max(256), decision: rawRetrievalDecisionSchema }).strict();

package/dist/internal/contracts/observation.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema, } from './common.js';
+export const observationKindSchema = z.enum([
+    'SOURCE_CHANGE',
+    'WORLD_SIGNAL',
+    'SOURCE_FAILURE',
+    'BUSINESS_FEEDBACK',
+    'AGENT_EVALUATION',
+    'CONTENT_FEEDBACK',
+    'OTHER',
+]);
+export const observationSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    observationId: idSchema,
+    projectKey: projectKeySchema.optional(),
+    projectRef: stableUriSchema.optional(),
+    kind: observationKindSchema,
+    observedAt: isoDateTimeSchema,
+    expiresAt: isoDateTimeSchema.optional(),
+    evidenceRefs: z.array(stableUriSchema).min(1).max(256),
+    payloadHash: sha256Schema.optional(),
+    summary: z.string().trim().min(1).max(4000).optional(),
+}).strict();
+export const signalLaneSchema = z.enum(['DEMAND', 'PAIN', 'COMMERCIAL', 'OTHER']);
+export const velocityStateSchema = z.enum(['NEW', 'RISING', 'STABLE', 'FALLING', 'REAPPEARED', 'UNKNOWN']);
+export const signalObservationSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    observationId: idSchema,
+    projectKey: projectKeySchema.optional(),
+    projectRef: stableUriSchema.optional(),
+    observedAt: isoDateTimeSchema,
+    evidenceRefs: z.array(stableUriSchema).min(1).max(256),
+    signalFamily: z.string().trim().min(1).max(128),
+    subject: z.string().trim().min(1).max(1000),
+    lanes: z.array(signalLaneSchema).min(1).max(4),
+    velocity: velocityStateSchema,
+    attentionScore: z.number().finite().optional(),
+    sourceCount: z.number().int().nonnegative(),
+}).strict();