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

package/dist/internal/contracts/persistence.js

@@ -0,0 +1,239 @@
+import { z } from 'zod';
+import { artifactKindSchema } from './artifact.js';
+import { evidenceRefSchema } from './evidence.js';
+import { accessClassificationSchema, idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema, } from './common.js';
+import { sourceDeclaredStateSchema } from './source-governance.js';
+export const portableRelativePathSchema = z.string().trim().min(1).max(4096).superRefine((value, ctx) => {
+    if (value.startsWith('/') || value.includes('\\'))
+        ctx.addIssue({ code: 'custom', message: 'Path must be portable and relative' });
+    const parts = value.split('/');
+    if (parts.some((part) => !part || part === '.' || part === '..'))
+        ctx.addIssue({ code: 'custom', message: 'Path contains invalid segment' });
+});
+export const sourceSetRegistryHashSchema = z.object({
+    acquisitionSourceId: idSchema,
+    relativePath: portableRelativePathSchema,
+    contentHash: sha256Schema,
+}).strict();
+export const sourceSetItemBindingSchema = z.object({
+    acquisitionSourceId: idSchema,
+    concreteSourceId: idSchema,
+    authority: z.string().trim().min(1).max(512).nullable(),
+    access: accessClassificationSchema,
+    declaredGitSha: z.string().trim().min(1).max(128).nullable(),
+}).strict();
+export const sourceSetItemSchema = z.object({
+    itemId: idSchema,
+    kind: z.enum(['WEB', 'FILE']),
+    logicalSourceRef: stableUriSchema,
+    sourceIds: z.array(idSchema).min(1).max(64),
+    bindings: z.array(sourceSetItemBindingSchema).min(1).max(64),
+    contentPolicy: z.enum(['public-excerpt', 'metadata-only']),
+    cadenceMs: z.number().int().positive(),
+    url: z.url().nullable(),
+    rootBinding: projectKeySchema.nullable(),
+    relativePath: portableRelativePathSchema.nullable(),
+}).strict().superRefine((value, ctx) => {
+    if (value.kind === 'WEB' && (!value.url || value.rootBinding || value.relativePath))
+        ctx.addIssue({ code: 'custom', path: ['url'], message: 'WEB item requires url only' });
+    if (value.kind === 'FILE' && (value.url || !value.rootBinding || !value.relativePath))
+        ctx.addIssue({ code: 'custom', path: ['relativePath'], message: 'FILE item requires rootBinding + relativePath only' });
+});
+export const sourceSetLogicalSourceSchema = z.object({
+    logicalSourceId: idSchema,
+    familyId: idSchema,
+    declaredState: sourceDeclaredStateSchema,
+    locator: stableUriSchema.nullable(),
+    acquisitionSourceIds: z.array(idSchema).max(64),
+    itemIds: z.array(idSchema).max(5000),
+}).strict();
+export const sourceSetSnapshotSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    sourceSetId: sha256Schema,
+    sourceSetRef: stableUriSchema,
+    projectKey: projectKeySchema,
+    programRevision: z.string().regex(/^[a-f0-9]{40,64}$/),
+    acquisitionConfigHash: sha256Schema,
+    sourceUniverseHash: sha256Schema.nullable(),
+    registryHashes: z.array(sourceSetRegistryHashSchema).max(256),
+    items: z.array(sourceSetItemSchema).max(20000),
+    logicalSources: z.array(sourceSetLogicalSourceSchema).max(5000),
+}).strict().superRefine((value, ctx) => {
+    const digest = value.sourceSetId.slice('sha256:'.length);
+    if (value.sourceSetRef !== `source-set://${value.projectKey}/${digest}`)
+        ctx.addIssue({ code: 'custom', path: ['sourceSetRef'], message: 'sourceSetRef must match sourceSetId' });
+    const itemIds = value.items.map((row) => row.itemId);
+    if (new Set(itemIds).size !== itemIds.length)
+        ctx.addIssue({ code: 'custom', path: ['items'], message: 'itemId must be unique' });
+    const logicalIds = value.logicalSources.map((row) => row.logicalSourceId);
+    if (new Set(logicalIds).size !== logicalIds.length)
+        ctx.addIssue({ code: 'custom', path: ['logicalSources'], message: 'logicalSourceId must be unique' });
+    const registryKeys = value.registryHashes.map((row) => `${row.acquisitionSourceId}\n${row.relativePath}`);
+    if (new Set(registryKeys).size !== registryKeys.length)
+        ctx.addIssue({ code: 'custom', path: ['registryHashes'], message: 'registry hash binding must be unique' });
+});
+export const sourceSetPointerSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    sourceSetId: sha256Schema,
+    sourceSetRef: stableUriSchema,
+    manifestRelativePath: portableRelativePathSchema,
+    updatedAt: isoDateTimeSchema,
+}).strict();
+export const libraryProjectionSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectionId: sha256Schema,
+    projectKey: projectKeySchema,
+    subjectType: z.enum(['ARTIFACT', 'EVIDENCE']),
+    subjectRef: stableUriSchema,
+    contentHash: sha256Schema,
+    mediaType: z.string().trim().min(1).max(256),
+    byteLength: z.number().int().nonnegative(),
+    relativePath: portableRelativePathSchema,
+    manifestRelativePath: portableRelativePathSchema,
+}).strict();
+export const deliverySupportProofSchema = z.object({
+    action: z.literal('ALLOW'),
+    supportState: z.string().trim().min(1).max(128),
+    semanticHash: sha256Schema,
+}).strict();
+export const deliveryConsumerRequestSchema = z.object({
+    mediaType: z.string().trim().min(1).max(256),
+    contentHash: sha256Schema,
+    byteLength: z.number().int().nonnegative(),
+}).strict();
+export const knowledgeDeliveryEnvelopeSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    deliveryId: sha256Schema,
+    producerProjectKey: projectKeySchema,
+    producerProjectRef: stableUriSchema.optional(),
+    consumerKey: projectKeySchema,
+    artifactRef: stableUriSchema,
+    artifactKind: artifactKindSchema,
+    artifactAccess: accessClassificationSchema,
+    contentHash: sha256Schema,
+    mediaType: z.string().trim().min(1).max(256),
+    byteLength: z.number().int().nonnegative(),
+    libraryPath: portableRelativePathSchema,
+    observedAt: isoDateTimeSchema.nullable(),
+    validUntil: isoDateTimeSchema.nullable(),
+    support: deliverySupportProofSchema.nullable(),
+    consumerRequest: deliveryConsumerRequestSchema.nullable(),
+    createdAt: isoDateTimeSchema,
+}).strict().superRefine((value, ctx) => { if (value.producerProjectRef) {
+    try {
+        const url = new URL(value.producerProjectRef);
+        if (url.protocol !== 'knowledge-project:' || url.hostname.toLowerCase() !== value.producerProjectKey.toLowerCase())
+            ctx.addIssue({ code: 'custom', path: ['producerProjectRef'], message: 'producerProjectRef project must match producer project' });
+    }
+    catch {
+        ctx.addIssue({ code: 'custom', path: ['producerProjectRef'], message: 'Invalid producerProjectRef' });
+    }
+} });
+export const knowledgeDeliveryClaimSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    deliveryId: sha256Schema,
+    producerProjectKey: projectKeySchema,
+    producerProjectRef: stableUriSchema.optional(),
+    consumerKey: projectKeySchema,
+    claimId: z.string().uuid(),
+    workerId: z.string().trim().min(1).max(128).regex(/^[A-Za-z0-9._-]+$/),
+    claimedAt: isoDateTimeSchema,
+    expiresAt: isoDateTimeSchema,
+}).strict().superRefine((value, ctx) => {
+    if (value.producerProjectRef) {
+        try {
+            const url = new URL(value.producerProjectRef);
+            if (url.protocol !== 'knowledge-project:' || url.hostname.toLowerCase() !== value.producerProjectKey.toLowerCase())
+                ctx.addIssue({ code: 'custom', path: ['producerProjectRef'], message: 'producerProjectRef project must match producer project' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['producerProjectRef'], message: 'Invalid producerProjectRef' });
+        }
+    }
+    const claimedAt = Date.parse(value.claimedAt), expiresAt = Date.parse(value.expiresAt), leaseSeconds = (expiresAt - claimedAt) / 1000;
+    if (expiresAt <= claimedAt)
+        ctx.addIssue({ code: 'custom', path: ['expiresAt'], message: 'Delivery claim expiry must be after claim time' });
+    else if (leaseSeconds < 30 || leaseSeconds > 3600)
+        ctx.addIssue({ code: 'custom', path: ['expiresAt'], message: 'Delivery claim lease must be between 30 and 3600 seconds' });
+});
+export const knowledgeDeliveryOutcomeSchema = z.enum(['DELIVERED', 'BLOCKED', 'FAILED_RETRYABLE', 'FAILED_TERMINAL']);
+export const knowledgeDeliveryReceiptSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    deliveryId: sha256Schema,
+    producerProjectKey: projectKeySchema,
+    producerProjectRef: stableUriSchema.optional(),
+    consumerKey: projectKeySchema,
+    artifactRef: stableUriSchema,
+    contentHash: sha256Schema,
+    outcome: knowledgeDeliveryOutcomeSchema,
+    attempts: z.number().int().positive().max(999999),
+    deliveredAt: isoDateTimeSchema,
+    nextAttemptAt: isoDateTimeSchema.nullable(),
+    externalRef: stableUriSchema.nullable(),
+    consumerResponseHash: sha256Schema.nullable(),
+    message: z.string().trim().min(1).max(4000).nullable(),
+}).strict().superRefine((value, ctx) => {
+    if (value.producerProjectRef) {
+        try {
+            const url = new URL(value.producerProjectRef);
+            if (url.protocol !== 'knowledge-project:' || url.hostname.toLowerCase() !== value.producerProjectKey.toLowerCase())
+                ctx.addIssue({ code: 'custom', path: ['producerProjectRef'], message: 'producerProjectRef project must match producer project' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['producerProjectRef'], message: 'Invalid producerProjectRef' });
+        }
+    }
+    if (value.outcome === 'DELIVERED' && value.nextAttemptAt)
+        ctx.addIssue({ code: 'custom', path: ['nextAttemptAt'], message: 'DELIVERED cannot schedule retry' });
+    if (value.outcome === 'FAILED_RETRYABLE' && !value.nextAttemptAt)
+        ctx.addIssue({ code: 'custom', path: ['nextAttemptAt'], message: 'FAILED_RETRYABLE requires nextAttemptAt' });
+    if (value.outcome === 'FAILED_RETRYABLE' && value.nextAttemptAt && Date.parse(value.nextAttemptAt) <= Date.parse(value.deliveredAt))
+        ctx.addIssue({ code: 'custom', path: ['nextAttemptAt'], message: 'Retry must be scheduled after this attempt completes' });
+    if (value.outcome !== 'FAILED_RETRYABLE' && value.nextAttemptAt)
+        ctx.addIssue({ code: 'custom', path: ['nextAttemptAt'], message: 'Only retryable failure may schedule retry' });
+});
+export const distributionConsumerSchema = z.object({
+    consumerKey: projectKeySchema,
+    enabled: z.boolean(),
+    artifactKinds: z.array(artifactKindSchema).min(1).max(16),
+    acceptedAccess: z.array(accessClassificationSchema).min(1).max(7),
+    supportPolicy: z.enum(['NONE', 'REQUIRE_ALLOW']),
+    adapter: z.string().trim().min(1).max(128),
+}).strict().superRefine((value, ctx) => {
+    if (value.artifactKinds.some((kind) => ['KNOWLEDGE', 'INSIGHT'].includes(kind)) && value.supportPolicy !== 'REQUIRE_ALLOW') {
+        ctx.addIssue({ code: 'custom', path: ['supportPolicy'], message: 'Knowledge/Insight distribution requires REQUIRE_ALLOW' });
+    }
+    if (new Set(value.acceptedAccess).size !== value.acceptedAccess.length)
+        ctx.addIssue({ code: 'custom', path: ['acceptedAccess'], message: 'acceptedAccess must be unique' });
+});
+export const distributionConfigSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    consumers: z.array(distributionConsumerSchema).max(128),
+}).strict().superRefine((value, ctx) => {
+    const keys = value.consumers.map((row) => row.consumerKey);
+    if (new Set(keys).size !== keys.length)
+        ctx.addIssue({ code: 'custom', path: ['consumers'], message: 'consumerKey must be unique' });
+});
+export const durableEvidenceManifestSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    evidenceRef: stableUriSchema,
+    evidence: evidenceRefSchema,
+}).strict().superRefine((value, ctx) => {
+    if (value.evidence.projectKey !== value.projectKey)
+        ctx.addIssue({ code: 'custom', path: ['evidence', 'projectKey'], message: 'Durable Evidence project must match manifest project' });
+    const expected = `evidence://${value.projectKey}/${encodeURIComponent(value.evidence.evidenceId)}`;
+    if (value.evidenceRef !== expected)
+        ctx.addIssue({ code: 'custom', path: ['evidenceRef'], message: 'Durable Evidence ref must match evidence identity' });
+    if (value.evidence.sourceSetRef) {
+        try {
+            if (new URL(value.evidence.sourceSetRef).hostname.toLowerCase() !== value.projectKey.toLowerCase())
+                ctx.addIssue({ code: 'custom', path: ['evidence', 'sourceSetRef'], message: 'Source Set project must match Evidence project' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['evidence', 'sourceSetRef'], message: 'Invalid Source Set ref' });
+        }
+    }
+});

package/dist/internal/contracts/project-intent.d.ts

@@ -0,0 +1,218 @@
+import { z } from 'zod';
+/**
+ * Attribution for an Agent-native Knowledge write. This is provenance, not an
+ * authorization decision. agentId is deliberately nullable because humans,
+ * schedulers and migrations may write without an Agent identity.
+ */
+export declare const knowledgeActorContextSchema: z.ZodObject<{
+    tenantId: z.ZodString;
+    userId: z.ZodString;
+    agentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export declare const projectIntentScopeSchema: z.ZodObject<{
+    scopeId: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+    sourceRequirements: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    sourceFamilies: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    notes: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export declare const projectIdentitySchema: z.ZodObject<{
+    name: z.ZodString;
+    summary: z.ZodString;
+    domains: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    notes: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export declare const projectIntentBasisSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    projectKey: z.ZodString;
+    actor: z.ZodObject<{
+        tenantId: z.ZodString;
+        userId: z.ZodString;
+        agentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>;
+    projectIdentity: z.ZodObject<{
+        name: z.ZodString;
+        summary: z.ZodString;
+        domains: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        notes: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>;
+    scopes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        scopeId: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodString;
+        sourceRequirements: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        sourceFamilies: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        notes: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export declare const projectIntentSnapshotSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    projectKey: z.ZodString;
+    actor: z.ZodObject<{
+        tenantId: z.ZodString;
+        userId: z.ZodString;
+        agentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>;
+    projectIdentity: z.ZodObject<{
+        name: z.ZodString;
+        summary: z.ZodString;
+        domains: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        notes: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>;
+    scopes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        scopeId: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodString;
+        sourceRequirements: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        sourceFamilies: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        notes: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>>;
+    projectRef: z.ZodString;
+    revisionId: z.ZodString;
+    revisionRef: z.ZodString;
+}, z.core.$strict>;
+export declare const projectIntentPointerSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    projectKey: z.ZodString;
+    tenantId: z.ZodString;
+    projectRef: z.ZodString;
+    revisionId: z.ZodString;
+    revisionRef: z.ZodString;
+    manifestRelativePath: z.ZodString;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const collectionRefreshSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    mode: z.ZodLiteral<"MANUAL">;
+}, z.core.$strict>, z.ZodObject<{
+    mode: z.ZodLiteral<"INTERVAL">;
+    intervalSeconds: z.ZodNumber;
+}, z.core.$strict>], "mode">;
+export declare const acquisitionTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"URL">;
+    locator: z.ZodURL;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"FILE">;
+    rootBinding: z.ZodString;
+    relativePath: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"EXECUTOR">;
+    executorId: z.ZodString;
+    bindingRef: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    parameters: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>>>;
+}, z.core.$strict>], "kind">;
+export declare const projectSourceBasisSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    projectKey: z.ZodString;
+    actor: z.ZodObject<{
+        tenantId: z.ZodString;
+        userId: z.ZodString;
+        agentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"URL">;
+        locator: z.ZodURL;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"FILE">;
+        rootBinding: z.ZodString;
+        relativePath: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"EXECUTOR">;
+        executorId: z.ZodString;
+        bindingRef: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        parameters: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>>>;
+    }, z.core.$strict>], "kind">;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    access: z.ZodDefault<z.ZodEnum<{
+        PUBLIC: "PUBLIC";
+        PUBLIC_METADATA: "PUBLIC_METADATA";
+        TENANT: "TENANT";
+        INTERNAL: "INTERNAL";
+        FDE_INTERNAL: "FDE_INTERNAL";
+        ACCESS_CONTROLLED: "ACCESS_CONTROLLED";
+        UNKNOWN: "UNKNOWN";
+    }>>;
+    scopeIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    sourceFamilies: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    purpose: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    refresh: z.ZodDefault<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        mode: z.ZodLiteral<"MANUAL">;
+    }, z.core.$strict>, z.ZodObject<{
+        mode: z.ZodLiteral<"INTERVAL">;
+        intervalSeconds: z.ZodNumber;
+    }, z.core.$strict>], "mode">>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+}, z.core.$strict>;
+export declare const projectSourceSnapshotSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    projectKey: z.ZodString;
+    actor: z.ZodObject<{
+        tenantId: z.ZodString;
+        userId: z.ZodString;
+        agentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"URL">;
+        locator: z.ZodURL;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"FILE">;
+        rootBinding: z.ZodString;
+        relativePath: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"EXECUTOR">;
+        executorId: z.ZodString;
+        bindingRef: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        parameters: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>>>;
+    }, z.core.$strict>], "kind">;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    access: z.ZodDefault<z.ZodEnum<{
+        PUBLIC: "PUBLIC";
+        PUBLIC_METADATA: "PUBLIC_METADATA";
+        TENANT: "TENANT";
+        INTERNAL: "INTERNAL";
+        FDE_INTERNAL: "FDE_INTERNAL";
+        ACCESS_CONTROLLED: "ACCESS_CONTROLLED";
+        UNKNOWN: "UNKNOWN";
+    }>>;
+    scopeIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    sourceFamilies: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    purpose: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    refresh: z.ZodDefault<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        mode: z.ZodLiteral<"MANUAL">;
+    }, z.core.$strict>, z.ZodObject<{
+        mode: z.ZodLiteral<"INTERVAL">;
+        intervalSeconds: z.ZodNumber;
+    }, z.core.$strict>], "mode">>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    projectRef: z.ZodString;
+    projectIntentRef: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    targetId: z.ZodString;
+    sourceId: z.ZodString;
+    revisionId: z.ZodString;
+    sourceRef: z.ZodString;
+    revisionRef: z.ZodString;
+}, z.core.$strict>;
+export declare const projectSourcePointerSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    projectKey: z.ZodString;
+    projectRef: z.ZodString;
+    projectIntentRef: z.ZodNullable<z.ZodString>;
+    sourceId: z.ZodString;
+    targetId: z.ZodString;
+    sourceRef: z.ZodString;
+    revisionId: z.ZodString;
+    revisionRef: z.ZodString;
+    manifestRelativePath: z.ZodString;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type KnowledgeActorContext = z.infer<typeof knowledgeActorContextSchema>;
+export type ProjectIntentScope = z.infer<typeof projectIntentScopeSchema>;
+export type ProjectIdentity = z.infer<typeof projectIdentitySchema>;
+export type ProjectIntentBasis = z.infer<typeof projectIntentBasisSchema>;
+export type ProjectIntentSnapshot = z.infer<typeof projectIntentSnapshotSchema>;
+export type ProjectIntentPointer = z.infer<typeof projectIntentPointerSchema>;
+export type CollectionRefresh = z.infer<typeof collectionRefreshSchema>;
+export type AcquisitionTarget = z.infer<typeof acquisitionTargetSchema>;
+export type ProjectSourceBasis = z.infer<typeof projectSourceBasisSchema>;
+export type ProjectSourceSnapshot = z.infer<typeof projectSourceSnapshotSchema>;
+export type ProjectSourcePointer = z.infer<typeof projectSourcePointerSchema>;

package/dist/internal/contracts/project-intent.js

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+import { accessClassificationSchema, idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema, } from './common.js';
+const text = (max) => z.string().trim().min(1).max(max);
+const optionalText = (max) => z.string().trim().min(1).max(max).nullable().default(null);
+/**
+ * Attribution for an Agent-native Knowledge write. This is provenance, not an
+ * authorization decision. agentId is deliberately nullable because humans,
+ * schedulers and migrations may write without an Agent identity.
+ */
+export const knowledgeActorContextSchema = z.object({
+    tenantId: idSchema,
+    userId: idSchema,
+    agentId: idSchema.nullable().default(null),
+}).strict();
+export const projectIntentScopeSchema = z.object({
+    scopeId: idSchema,
+    title: text(256),
+    description: text(4000),
+    sourceRequirements: z.array(text(1000)).max(256).default([]),
+    sourceFamilies: z.array(idSchema).max(256).default([]),
+    notes: optionalText(4000),
+}).strict();
+export const projectIdentitySchema = z.object({
+    name: text(256),
+    summary: text(4000),
+    domains: z.array(text(256)).max(256).default([]),
+    notes: optionalText(4000),
+}).strict();
+export const projectIntentBasisSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    actor: knowledgeActorContextSchema,
+    projectIdentity: projectIdentitySchema,
+    scopes: z.array(projectIntentScopeSchema).max(1000).default([]),
+}).strict().superRefine((value, ctx) => {
+    const seen = new Set();
+    for (let i = 0; i < value.scopes.length; i += 1) {
+        const scopeId = value.scopes[i].scopeId;
+        if (seen.has(scopeId))
+            ctx.addIssue({ code: 'custom', path: ['scopes', i, 'scopeId'], message: 'scopeId must be unique' });
+        seen.add(scopeId);
+    }
+});
+export const projectIntentSnapshotSchema = projectIntentBasisSchema.extend({
+    projectRef: stableUriSchema,
+    revisionId: sha256Schema,
+    revisionRef: stableUriSchema,
+}).strict();
+export const projectIntentPointerSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    tenantId: idSchema,
+    projectRef: stableUriSchema,
+    revisionId: sha256Schema,
+    revisionRef: stableUriSchema,
+    manifestRelativePath: text(2048),
+    updatedAt: isoDateTimeSchema,
+}).strict();
+export const collectionRefreshSchema = z.discriminatedUnion('mode', [
+    z.object({ mode: z.literal('MANUAL') }).strict(),
+    z.object({ mode: z.literal('INTERVAL'), intervalSeconds: z.number().int().min(60).max(31_536_000) }).strict(),
+]);
+/** Project-neutral executable target. Project/domain semantics stay on ProjectSource. */
+const relativeTargetPathSchema = z.string().trim().min(1).max(2048).superRefine((value, ctx) => {
+    if (value.includes('\\') || value.startsWith('/') || value.endsWith('/')) {
+        ctx.addIssue({ code: 'custom', message: 'FILE target path must be a normalized relative file path' });
+        return;
+    }
+    const parts = value.split('/');
+    if (parts.some((part) => !part || part === '.' || part === '..'))
+        ctx.addIssue({ code: 'custom', message: 'FILE target path must not contain empty, dot or parent segments' });
+});
+const executorParameterScalarSchema = z.union([z.string().max(4000), z.number().finite(), z.boolean(), z.null()]);
+const executorParameterValueSchema = z.union([executorParameterScalarSchema, z.array(executorParameterScalarSchema).max(256)]);
+const urlAcquisitionTargetSchema = z.object({ kind: z.literal('URL'), locator: z.url() }).strict();
+const fileAcquisitionTargetSchema = z.object({ kind: z.literal('FILE'), rootBinding: projectKeySchema, relativePath: relativeTargetPathSchema }).strict();
+const executorAcquisitionTargetSchema = z.object({
+    kind: z.literal('EXECUTOR'), executorId: idSchema, bindingRef: stableUriSchema.nullable().default(null), parameters: z.record(z.string().trim().min(1).max(128), executorParameterValueSchema).default({}),
+}).strict().superRefine((value, ctx) => {
+    if (Object.keys(value.parameters).length > 128)
+        ctx.addIssue({ code: 'custom', path: ['parameters'], message: 'EXECUTOR target supports at most 128 parameters' });
+    if (Buffer.byteLength(JSON.stringify(value.parameters), 'utf8') > 32 * 1024)
+        ctx.addIssue({ code: 'custom', path: ['parameters'], message: 'EXECUTOR target parameters exceed 32 KiB' });
+});
+export const acquisitionTargetSchema = z.discriminatedUnion('kind', [urlAcquisitionTargetSchema, fileAcquisitionTargetSchema, executorAcquisitionTargetSchema]);
+const metadataScalarSchema = z.union([z.string().max(4000), z.number(), z.boolean(), z.null()]);
+export const projectSourceBasisSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    actor: knowledgeActorContextSchema,
+    target: acquisitionTargetSchema,
+    enabled: z.boolean().default(true),
+    access: accessClassificationSchema.default('PUBLIC'),
+    scopeIds: z.array(idSchema).max(256).default([]),
+    sourceFamilies: z.array(idSchema).max(256).default([]),
+    purpose: optionalText(4000),
+    refresh: collectionRefreshSchema.default({ mode: 'MANUAL' }),
+    metadata: z.record(z.string().trim().min(1).max(128), metadataScalarSchema).default({}),
+}).strict();
+export const projectSourceSnapshotSchema = projectSourceBasisSchema.extend({
+    projectRef: stableUriSchema,
+    projectIntentRef: stableUriSchema.nullable().default(null),
+    targetId: sha256Schema,
+    sourceId: idSchema,
+    revisionId: sha256Schema,
+    sourceRef: stableUriSchema,
+    revisionRef: stableUriSchema,
+}).strict();
+export const projectSourcePointerSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    projectRef: stableUriSchema,
+    projectIntentRef: stableUriSchema.nullable(),
+    sourceId: idSchema,
+    targetId: sha256Schema,
+    sourceRef: stableUriSchema,
+    revisionId: sha256Schema,
+    revisionRef: stableUriSchema,
+    manifestRelativePath: text(2048),
+    updatedAt: isoDateTimeSchema,
+}).strict();