@native-knowledge/knowledge-sdk 0.1.0-rc.1 → 0.1.0-rc.2

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

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();