@oscharko-dev/keiko-contracts 0.2.0

package/dist/local-knowledge-validation.d.ts

@@ -0,0 +1,20 @@
+import type { CapsuleSet, ConnectorGraphState, ConnectorNode, EmbeddingModelIdentity, KnowledgeCapsule, KnowledgeSourceScope } from "./local-knowledge.js";
+import type { CapsuleReindexRequest } from "./local-knowledge-records.js";
+export interface ValidationOk<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+export interface ValidationFail {
+    readonly ok: false;
+    readonly errors: readonly string[];
+}
+export type LocalKnowledgeValidation<T> = ValidationOk<T> | ValidationFail;
+export declare function isSafeDisplaySummary(value: unknown): value is string;
+export declare function validateEmbeddingModelIdentity(input: unknown): LocalKnowledgeValidation<EmbeddingModelIdentity>;
+export declare function validateKnowledgeSourceScope(input: unknown): LocalKnowledgeValidation<KnowledgeSourceScope>;
+export declare function validateKnowledgeCapsule(input: unknown): LocalKnowledgeValidation<KnowledgeCapsule>;
+export declare function validateCapsuleSet(input: unknown): LocalKnowledgeValidation<CapsuleSet>;
+export declare function validateCapsuleReindexRequest(input: unknown): LocalKnowledgeValidation<CapsuleReindexRequest>;
+export declare function validateConnectorGraphState(input: unknown): LocalKnowledgeValidation<ConnectorGraphState>;
+export type { ConnectorNode };
+//# sourceMappingURL=local-knowledge-validation.d.ts.map

package/dist/local-knowledge-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-knowledge-validation.d.ts","sourceRoot":"","sources":["../src/local-knowledge-validation.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,UAAU,EACV,mBAAmB,EACnB,aAAa,EACb,sBAAsB,EACtB,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAiB1E,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AACD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AACD,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC;AAmC3E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAQpE;AAyFD,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,GACb,wBAAwB,CAAC,sBAAsB,CAAC,CA2BlD;AA+ED,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,OAAO,GACb,wBAAwB,CAAC,oBAAoB,CAAC,CAuBhD;AAwDD,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,GACb,wBAAwB,CAAC,gBAAgB,CAAC,CA4B5C;AAgBD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,wBAAwB,CAAC,UAAU,CAAC,CAuBvF;AAED,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,GACb,wBAAwB,CAAC,qBAAqB,CAAC,CAqBjD;AAmKD,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,GACb,wBAAwB,CAAC,mBAAmB,CAAC,CAuB/C;AAID,YAAY,EAAE,aAAa,EAAE,CAAC"}

package/dist/local-knowledge-validation.js

@@ -0,0 +1,487 @@
+// Pure validators for the Local Knowledge Connector contracts (Epic #189, Issue #191).
+// No filesystem reads, no clock reads, no crypto, no randomness; these helpers only inspect
+// the structure of an `unknown` payload and report which invariants failed. Producers and
+// consumers wire these at trust-boundary edges (BFF, audit, indexer entry points).
+//
+// Each validator returns a discriminated `{ ok: true; value } | { ok: false; errors }` so
+// downstream code can branch without throwing. Errors are short, machine-readable strings,
+// one per failed invariant, to keep diagnostics deterministic for evaluation harnesses.
+import { CAPSULE_ANSWER_GROUNDING_POLICIES, CAPSULE_LIFECYCLE_STATES, CAPSULE_METADATA_KEY_MAX_CHARS, CAPSULE_METADATA_MAX_KEYS, CAPSULE_METADATA_VALUE_MAX_CHARS, CAPSULE_OUTPUT_MODES, CAPSULE_RETRIEVAL_EFFORTS, CONNECTOR_NODE_KINDS, EMBEDDING_VECTOR_METRICS, KNOWLEDGE_SOURCE_SCOPE_KINDS, } from "./local-knowledge.js";
+import { CAPSULE_REINDEX_MODES } from "./local-knowledge-records.js";
+import { isSafeScopePath, isSafeStorageReference } from "./local-knowledge-paths.js";
+// ─── Shared primitive guards ──────────────────────────────────────────────────
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyTrimmedString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isFiniteNonNegativeNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function isFinitePositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+// Soft-cap chosen to keep browser surfaces safe (matches the upper bound a Conversation
+// Center summary card will render without truncation). NUL and the ASCII control range
+// are rejected because they corrupt terminal output and many UI text renderers; \n and \t
+// are explicitly allowed since legitimate display strings carry line breaks.
+const SAFE_DISPLAY_MAX_CHARS = 4096;
+// Intentionally matches control characters; this is the entire purpose of the safety
+// gate. The `no-control-regex` lint rule guards against accidental control matches, not
+// deliberate ones.
+// eslint-disable-next-line no-control-regex
+const FORBIDDEN_CONTROL_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/;
+export function isSafeDisplaySummary(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    if (value.length > SAFE_DISPLAY_MAX_CHARS) {
+        return false;
+    }
+    return !FORBIDDEN_CONTROL_RE.test(value);
+}
+function isSafeDisplayString(value) {
+    return isNonEmptyTrimmedString(value) && isSafeDisplaySummary(value);
+}
+function validateSafeDisplayStringField(errors, field, value) {
+    if (!isSafeDisplayString(value)) {
+        errors.push(`${field} must be a browser-safe non-empty trimmed string`);
+    }
+}
+function validateSafeDisplayStringArrayField(errors, field, value) {
+    if (!Array.isArray(value)) {
+        errors.push(`${field} must be a string array`);
+        return;
+    }
+    for (const entry of value) {
+        if (!isSafeDisplayString(entry)) {
+            errors.push(`${field} entry must be a browser-safe non-empty trimmed string`);
+            return;
+        }
+    }
+}
+function validateSafeMetadataMap(errors, field, value) {
+    if (value === undefined) {
+        return;
+    }
+    if (!isRecord(value)) {
+        errors.push(`${field} must be an object when set`);
+        return;
+    }
+    const entries = Object.entries(value);
+    if (entries.length > CAPSULE_METADATA_MAX_KEYS) {
+        errors.push(`${field} may contain at most ${String(CAPSULE_METADATA_MAX_KEYS)} entries`);
+        return;
+    }
+    for (const [key, entryValue] of entries) {
+        if (!isSafeDisplayString(key) || key.length > CAPSULE_METADATA_KEY_MAX_CHARS) {
+            errors.push(`${field} keys must be browser-safe non-empty strings no longer than ${String(CAPSULE_METADATA_KEY_MAX_CHARS)} characters`);
+            return;
+        }
+        if (typeof entryValue !== "string" ||
+            !isSafeDisplaySummary(entryValue) ||
+            entryValue.length > CAPSULE_METADATA_VALUE_MAX_CHARS) {
+            errors.push(`${field} values must be browser-safe strings no longer than ${String(CAPSULE_METADATA_VALUE_MAX_CHARS)} characters`);
+            return;
+        }
+    }
+}
+function validateOnlyKeys(record, allowedKeys, field, errors) {
+    const allowed = new Set(allowedKeys);
+    for (const key of Object.keys(record)) {
+        if (!allowed.has(key)) {
+            errors.push(`${field} must not include ${key}`);
+            return;
+        }
+    }
+}
+// ─── EmbeddingModelIdentity ───────────────────────────────────────────────────
+function pushBadEnum(errors, field, value, allowed) {
+    if (typeof value !== "string" || !allowed.includes(value)) {
+        errors.push(`${field} must be one of ${allowed.join("|")}`);
+    }
+}
+export function validateEmbeddingModelIdentity(input) {
+    const errors = [];
+    if (!isRecord(input)) {
+        return { ok: false, errors: ["embeddingModelIdentity must be an object"] };
+    }
+    if (!isNonEmptyTrimmedString(input.provider)) {
+        errors.push("embeddingModelIdentity.provider must be a non-empty string");
+    }
+    if (!isNonEmptyTrimmedString(input.modelId)) {
+        errors.push("embeddingModelIdentity.modelId must be a non-empty string");
+    }
+    if (!isFinitePositiveInteger(input.vectorDimensions)) {
+        errors.push("embeddingModelIdentity.vectorDimensions must be a positive integer");
+    }
+    pushBadEnum(errors, "embeddingModelIdentity.vectorMetric", input.vectorMetric, EMBEDDING_VECTOR_METRICS);
+    if (input.modelRevision !== undefined && !isNonEmptyTrimmedString(input.modelRevision)) {
+        errors.push("embeddingModelIdentity.modelRevision must be a non-empty string when set");
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, value: input };
+}
+// ─── KnowledgeSourceScope ─────────────────────────────────────────────────────
+function validateGlobs(field, globs, errors) {
+    if (globs === undefined) {
+        return;
+    }
+    if (!isStringArray(globs)) {
+        errors.push(`${field} must be a string array when set`);
+        return;
+    }
+    if (globs.length === 0) {
+        errors.push(`${field} must be omitted instead of set to an empty array`);
+        return;
+    }
+    const seen = new Set();
+    for (const glob of globs) {
+        if (glob.length === 0 || glob.includes("\0") || !isSafeStorageReference(glob)) {
+            errors.push(`${field} entry must be a safe relative NUL-free glob`);
+            return;
+        }
+        if (seen.has(glob)) {
+            errors.push(`${field} entries must be unique`);
+            return;
+        }
+        seen.add(glob);
+    }
+}
+function validateGlobOverlap(input, errors) {
+    if (!isStringArray(input.includeGlobs) || !isStringArray(input.excludeGlobs)) {
+        return;
+    }
+    const include = new Set(input.includeGlobs);
+    for (const exclude of input.excludeGlobs) {
+        if (include.has(exclude)) {
+            errors.push("scope.excludeGlobs entries must not exactly cancel includeGlobs entries");
+            return;
+        }
+    }
+}
+function validateFolderScope(input, errors) {
+    if (typeof input.rootPath !== "string" || !isSafeScopePath(input.rootPath)) {
+        errors.push("scope.rootPath is unsafe or empty");
+    }
+    if (typeof input.recursive !== "boolean") {
+        errors.push("scope.recursive must be a boolean");
+    }
+    validateGlobs("scope.includeGlobs", input.includeGlobs, errors);
+    validateGlobs("scope.excludeGlobs", input.excludeGlobs, errors);
+    validateGlobOverlap(input, errors);
+}
+function validateRepositoryScope(input, errors) {
+    if (typeof input.repositoryRoot !== "string" || !isSafeScopePath(input.repositoryRoot)) {
+        errors.push("scope.repositoryRoot is unsafe or empty");
+    }
+    validateGlobs("scope.includeGlobs", input.includeGlobs, errors);
+    validateGlobs("scope.excludeGlobs", input.excludeGlobs, errors);
+    validateGlobOverlap(input, errors);
+}
+function validateFilesScope(input, errors) {
+    if (typeof input.rootPath !== "string" || !isSafeScopePath(input.rootPath)) {
+        errors.push("scope.rootPath is unsafe or empty");
+    }
+    if (!Array.isArray(input.files) || input.files.length === 0) {
+        errors.push("scope.files must be a non-empty array");
+        return;
+    }
+    for (const entry of input.files) {
+        if (typeof entry !== "string" || !isSafeStorageReference(entry)) {
+            errors.push("scope.files entry is unsafe or empty");
+            return;
+        }
+    }
+}
+export function validateKnowledgeSourceScope(input) {
+    if (!isRecord(input)) {
+        return { ok: false, errors: ["scope must be an object"] };
+    }
+    const kind = input.kind;
+    if (!KNOWLEDGE_SOURCE_SCOPE_KINDS.includes(kind)) {
+        return {
+            ok: false,
+            errors: [`scope.kind must be one of ${KNOWLEDGE_SOURCE_SCOPE_KINDS.join("|")}`],
+        };
+    }
+    const errors = [];
+    if (kind === "folder") {
+        validateFolderScope(input, errors);
+    }
+    else if (kind === "repository") {
+        validateRepositoryScope(input, errors);
+    }
+    else {
+        validateFilesScope(input, errors);
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, value: input };
+}
+// ─── KnowledgeCapsule ─────────────────────────────────────────────────────────
+function validateCapsuleEnums(input, errors) {
+    pushBadEnum(errors, "capsule.retrievalEffort", input.retrievalEffort, CAPSULE_RETRIEVAL_EFFORTS);
+    pushBadEnum(errors, "capsule.outputMode", input.outputMode, CAPSULE_OUTPUT_MODES);
+    pushBadEnum(errors, "capsule.answerGroundingPolicy", input.answerGroundingPolicy, CAPSULE_ANSWER_GROUNDING_POLICIES);
+    pushBadEnum(errors, "capsule.lifecycleState", input.lifecycleState, CAPSULE_LIFECYCLE_STATES);
+}
+function validateCapsuleTimestamps(input, errors) {
+    if (!isFiniteNonNegativeNumber(input.createdAt)) {
+        errors.push("capsule.createdAt must be a finite non-negative number");
+    }
+    if (!isFiniteNonNegativeNumber(input.updatedAt)) {
+        errors.push("capsule.updatedAt must be a finite non-negative number");
+    }
+}
+function validateCapsuleSourceLineage(input, errors) {
+    if (!Array.isArray(input.sourceIds) || input.sourceIds.length === 0) {
+        errors.push("capsule.sourceIds must be a non-empty array");
+        return;
+    }
+    for (const id of input.sourceIds) {
+        if (!isNonEmptyTrimmedString(id)) {
+            errors.push("capsule.sourceIds entry must be a non-empty string");
+            return;
+        }
+    }
+}
+function validateKnowledgeCapsuleDisplayMetadata(input, errors) {
+    validateSafeDisplayStringField(errors, "capsule.displayName", input.displayName);
+    if (input.description !== undefined) {
+        validateSafeDisplayStringField(errors, "capsule.description", input.description);
+    }
+    if (input.sourceRoutingInstructions !== undefined) {
+        validateSafeDisplayStringField(errors, "capsule.sourceRoutingInstructions", input.sourceRoutingInstructions);
+    }
+    validateSafeDisplayStringArrayField(errors, "capsule.tags", input.tags);
+    validateSafeMetadataMap(errors, "capsule.metadata", input.metadata);
+}
+export function validateKnowledgeCapsule(input) {
+    if (!isRecord(input)) {
+        return { ok: false, errors: ["capsule must be an object"] };
+    }
+    const errors = [];
+    if (!isNonEmptyTrimmedString(input.id)) {
+        errors.push("capsule.id must be a non-empty string");
+    }
+    validateKnowledgeCapsuleDisplayMetadata(input, errors);
+    validateCapsuleSourceLineage(input, errors);
+    validateCapsuleEnums(input, errors);
+    const identityResult = validateEmbeddingModelIdentity(input.embeddingModelIdentity);
+    if (!identityResult.ok) {
+        for (const reason of identityResult.errors) {
+            errors.push(`capsule.${reason}`);
+        }
+    }
+    if (typeof input.storageReference !== "string" ||
+        !isSafeStorageReference(input.storageReference)) {
+        errors.push("capsule.storageReference must be a safe relative path");
+    }
+    validateCapsuleTimestamps(input, errors);
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, value: input };
+}
+// ─── CapsuleSet ───────────────────────────────────────────────────────────────
+function validateCapsuleSetCapsuleIds(input, errors) {
+    if (!Array.isArray(input.capsuleIds) || input.capsuleIds.length === 0) {
+        errors.push("capsuleSet.capsuleIds must be a non-empty array");
+        return;
+    }
+    for (const id of input.capsuleIds) {
+        if (!isNonEmptyTrimmedString(id)) {
+            errors.push("capsuleSet.capsuleIds entry must be a non-empty string");
+            return;
+        }
+    }
+}
+export function validateCapsuleSet(input) {
+    if (!isRecord(input)) {
+        return { ok: false, errors: ["capsuleSet must be an object"] };
+    }
+    const errors = [];
+    if (!isNonEmptyTrimmedString(input.id)) {
+        errors.push("capsuleSet.id must be a non-empty string");
+    }
+    if (!isSafeDisplayString(input.displayName)) {
+        errors.push("capsuleSet.displayName must be a browser-safe non-empty trimmed string");
+    }
+    if (input.description !== undefined && !isSafeDisplayString(input.description)) {
+        errors.push("capsuleSet.description must be a browser-safe non-empty trimmed string");
+    }
+    validateSafeDisplayStringArrayField(errors, "capsuleSet.tags", input.tags);
+    validateCapsuleSetCapsuleIds(input, errors);
+    if (!isFiniteNonNegativeNumber(input.composedAt)) {
+        errors.push("capsuleSet.composedAt must be a finite non-negative number");
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, value: input };
+}
+export function validateCapsuleReindexRequest(input) {
+    if (!isRecord(input)) {
+        return { ok: false, errors: ["reindexRequest must be an object"] };
+    }
+    const errors = [];
+    if (!isNonEmptyTrimmedString(input.capsuleId)) {
+        errors.push("reindexRequest.capsuleId must be a non-empty string");
+    }
+    if (input.mode !== undefined &&
+        !CAPSULE_REINDEX_MODES.includes(input.mode)) {
+        errors.push(`reindexRequest.mode must be one of ${CAPSULE_REINDEX_MODES.join("|")}`);
+    }
+    if (input.force !== undefined && typeof input.force !== "boolean") {
+        errors.push("reindexRequest.force must be a boolean when provided");
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, value: input };
+}
+// ─── ConnectorGraphState ──────────────────────────────────────────────────────
+function validateFilesWindowNode(node, errors) {
+    validateOnlyKeys(node, ["kind", "nodeId", "scope"], "graph.nodes entry.files-window", errors);
+    const scopeResult = validateKnowledgeSourceScope(node.scope);
+    if (!scopeResult.ok) {
+        for (const reason of scopeResult.errors) {
+            errors.push(`graph.nodes entry.files-window.${reason}`);
+        }
+    }
+}
+function validateLocalKnowledgeNodeTarget(target, errors) {
+    if (!isRecord(target)) {
+        errors.push("graph.nodes entry.local-knowledge.target must be an object");
+        return;
+    }
+    if (target.kind === "capsule") {
+        validateOnlyKeys(target, ["kind", "capsuleId"], "graph.nodes entry.local-knowledge.target.capsule", errors);
+        if (!isNonEmptyTrimmedString(target.capsuleId)) {
+            errors.push("graph.nodes entry.local-knowledge.target.capsuleId must be a non-empty string");
+        }
+        return;
+    }
+    if (target.kind === "capsule-set") {
+        validateOnlyKeys(target, ["kind", "capsuleSetId"], "graph.nodes entry.local-knowledge.target.capsule-set", errors);
+        if (!isNonEmptyTrimmedString(target.capsuleSetId)) {
+            errors.push("graph.nodes entry.local-knowledge.target.capsuleSetId must be a non-empty string");
+        }
+        return;
+    }
+    errors.push('graph.nodes entry.local-knowledge.target.kind must be "capsule" or "capsule-set"');
+}
+function validateLocalKnowledgeNode(node, errors) {
+    validateOnlyKeys(node, ["kind", "nodeId", "target"], "graph.nodes entry.local-knowledge", errors);
+    validateLocalKnowledgeNodeTarget(node.target, errors);
+}
+function validateConversationCenterNode(node, errors) {
+    validateOnlyKeys(node, ["kind", "nodeId", "conversationId", "route"], "graph.nodes entry.conversation-center", errors);
+    if (!isNonEmptyTrimmedString(node.conversationId)) {
+        errors.push("graph.nodes entry.conversation-center.conversationId must be a non-empty string");
+    }
+    if (!isNonEmptyTrimmedString(node.route)) {
+        errors.push("graph.nodes entry.conversation-center.route must be a non-empty string");
+    }
+}
+function collectNodeKinds(nodes, errors) {
+    const nodeKinds = new Map();
+    for (const node of nodes) {
+        if (!isRecord(node)) {
+            errors.push("graph.nodes entry must be an object");
+            continue;
+        }
+        if (!isNonEmptyTrimmedString(node.nodeId)) {
+            errors.push("graph.nodes entry must have a non-empty nodeId");
+            continue;
+        }
+        if (nodeKinds.has(node.nodeId)) {
+            errors.push(`graph.nodes contains a duplicate nodeId: ${node.nodeId}`);
+            continue;
+        }
+        if (typeof node.kind !== "string" ||
+            !CONNECTOR_NODE_KINDS.includes(node.kind)) {
+            errors.push("graph.nodes entry has an unknown kind");
+            continue;
+        }
+        nodeKinds.set(node.nodeId, node.kind);
+        if (node.kind === "files-window") {
+            validateFilesWindowNode(node, errors);
+        }
+        else if (node.kind === "local-knowledge") {
+            validateLocalKnowledgeNode(node, errors);
+        }
+        else {
+            validateConversationCenterNode(node, errors);
+        }
+    }
+    return nodeKinds;
+}
+function validateEdgeNodeId(field, nodeId, nodeKinds, errors) {
+    if (typeof nodeId !== "string" || !nodeKinds.has(nodeId)) {
+        errors.push(`graph.edges references unknown ${field}.nodeId`);
+        return undefined;
+    }
+    return nodeId;
+}
+function validateEdgeNodeKind(field, kind, nodeId, nodeKinds, errors) {
+    if (typeof kind !== "string" || !CONNECTOR_NODE_KINDS.includes(kind)) {
+        errors.push(`graph.edges ${field}.kind must be a known node kind`);
+        return;
+    }
+    if (nodeId !== undefined && nodeKinds.get(nodeId) !== kind) {
+        errors.push(`graph.edges ${field}.kind must match the referenced node kind`);
+    }
+}
+function validateEdgeRecord(edge, nodeKinds, errors) {
+    const from = edge.from;
+    const to = edge.to;
+    const fromId = validateEdgeNodeId("from", from.nodeId, nodeKinds, errors);
+    const toId = validateEdgeNodeId("to", to.nodeId, nodeKinds, errors);
+    validateEdgeNodeKind("from", from.kind, fromId, nodeKinds, errors);
+    validateEdgeNodeKind("to", to.kind, toId, nodeKinds, errors);
+    if (!isFiniteNonNegativeNumber(edge.createdAt)) {
+        errors.push("graph.edges entry must have a finite non-negative createdAt");
+    }
+}
+function validateEdges(edges, nodeKinds, errors) {
+    for (const edge of edges) {
+        if (!isRecord(edge) || !isRecord(edge.from) || !isRecord(edge.to)) {
+            errors.push("graph.edges entry must have from/to objects");
+            continue;
+        }
+        validateEdgeRecord(edge, nodeKinds, errors);
+    }
+}
+export function validateConnectorGraphState(input) {
+    if (!isRecord(input)) {
+        return { ok: false, errors: ["graph must be an object"] };
+    }
+    const errors = [];
+    if (input.schemaVersion !== "1") {
+        errors.push('graph.schemaVersion must be the literal "1"');
+    }
+    if (!Array.isArray(input.nodes)) {
+        return { ok: false, errors: [...errors, "graph.nodes must be an array"] };
+    }
+    if (!Array.isArray(input.edges)) {
+        return { ok: false, errors: [...errors, "graph.edges must be an array"] };
+    }
+    const nodeKinds = collectNodeKinds(input.nodes, errors);
+    validateEdges(input.edges, nodeKinds, errors);
+    if (!isFiniteNonNegativeNumber(input.updatedAt)) {
+        errors.push("graph.updatedAt must be a finite non-negative number");
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, value: input };
+}

package/dist/local-knowledge.d.ts

@@ -0,0 +1,158 @@
+export declare const LOCAL_KNOWLEDGE_SCHEMA_VERSION: "1";
+declare const KnowledgeCapsuleIdBrand: unique symbol;
+declare const KnowledgeSourceIdBrand: unique symbol;
+declare const CapsuleSetIdBrand: unique symbol;
+declare const DocumentIdBrand: unique symbol;
+declare const ChunkIdBrand: unique symbol;
+declare const VectorIdBrand: unique symbol;
+export type KnowledgeCapsuleId = string & {
+    readonly [KnowledgeCapsuleIdBrand]: true;
+};
+export type KnowledgeSourceId = string & {
+    readonly [KnowledgeSourceIdBrand]: true;
+};
+export type CapsuleSetId = string & {
+    readonly [CapsuleSetIdBrand]: true;
+};
+export type DocumentId = string & {
+    readonly [DocumentIdBrand]: true;
+};
+export type ChunkId = string & {
+    readonly [ChunkIdBrand]: true;
+};
+export type VectorId = string & {
+    readonly [VectorIdBrand]: true;
+};
+export type EmbeddingVectorMetric = "cosine" | "euclidean" | "dot";
+export declare const EMBEDDING_VECTOR_METRICS: readonly EmbeddingVectorMetric[];
+export interface EmbeddingModelIdentity {
+    readonly provider: string;
+    readonly modelId: string;
+    readonly vectorDimensions: number;
+    readonly vectorMetric: EmbeddingVectorMetric;
+    readonly modelRevision?: string;
+}
+export interface ParserDependencyVersion {
+    readonly packageName: string;
+    readonly version: string;
+}
+export interface ParserIdentity {
+    readonly parserId: string;
+    readonly parserVersion: string;
+    readonly dependencyVersions?: readonly ParserDependencyVersion[];
+}
+export type KnowledgeSourceScope = {
+    readonly kind: "folder";
+    readonly rootPath: string;
+    readonly recursive: boolean;
+    readonly includeGlobs?: readonly string[];
+    readonly excludeGlobs?: readonly string[];
+} | {
+    readonly kind: "repository";
+    readonly repositoryRoot: string;
+    readonly includeGlobs?: readonly string[];
+    readonly excludeGlobs?: readonly string[];
+} | {
+    readonly kind: "files";
+    readonly rootPath: string;
+    readonly files: readonly string[];
+};
+export type KnowledgeSourceScopeKind = KnowledgeSourceScope["kind"];
+export declare const KNOWLEDGE_SOURCE_SCOPE_KINDS: readonly KnowledgeSourceScopeKind[];
+export interface KnowledgeSource {
+    readonly id: KnowledgeSourceId;
+    readonly displayName: string;
+    readonly description?: string;
+    readonly tags: readonly string[];
+    readonly scope: KnowledgeSourceScope;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+export type CapsuleLifecycleState = "draft" | "indexing" | "ready" | "stale" | "deleting" | "error";
+export declare const CAPSULE_LIFECYCLE_STATES: readonly CapsuleLifecycleState[];
+export type CapsuleRetrievalEffort = "minimal" | "default" | "deep";
+export declare const CAPSULE_RETRIEVAL_EFFORTS: readonly CapsuleRetrievalEffort[];
+export type CapsuleOutputMode = "answers" | "snippets" | "raw";
+export declare const CAPSULE_OUTPUT_MODES: readonly CapsuleOutputMode[];
+export type CapsuleAnswerGroundingPolicy = "require-citations" | "require-citations-or-state-no-evidence" | "best-effort";
+export declare const CAPSULE_ANSWER_GROUNDING_POLICIES: readonly CapsuleAnswerGroundingPolicy[];
+export interface KnowledgeCapsule {
+    readonly id: KnowledgeCapsuleId;
+    readonly displayName: string;
+    readonly description?: string;
+    readonly tags: readonly string[];
+    readonly sourceIds: readonly KnowledgeSourceId[];
+    readonly sourceRoutingInstructions?: string;
+    readonly alwaysQuery?: boolean;
+    readonly retrievalEffort: CapsuleRetrievalEffort;
+    readonly outputMode: CapsuleOutputMode;
+    readonly answerGroundingPolicy: CapsuleAnswerGroundingPolicy;
+    readonly embeddingModelIdentity: EmbeddingModelIdentity;
+    readonly lifecycleState: CapsuleLifecycleState;
+    readonly storageReference: string;
+    readonly metadata?: Readonly<Record<string, string>>;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+export interface CapsuleSet {
+    readonly id: CapsuleSetId;
+    readonly displayName: string;
+    readonly description?: string;
+    readonly tags: readonly string[];
+    readonly capsuleIds: readonly KnowledgeCapsuleId[];
+    readonly composedAt: number;
+}
+export declare const CAPSULE_METADATA_MAX_KEYS: 16;
+export declare const CAPSULE_METADATA_KEY_MAX_CHARS: 128;
+export declare const CAPSULE_METADATA_VALUE_MAX_CHARS: 1024;
+export declare const CAPSULE_SET_MAX_MEMBERS: 16;
+export interface UpdateCapsulePatch {
+    readonly displayName?: string;
+    readonly description?: string;
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+export interface CreateCapsuleSetBody {
+    readonly displayName: string;
+    readonly description?: string;
+    readonly capsuleIds: readonly string[];
+}
+export type ConnectorNodeKind = "files-window" | "local-knowledge" | "conversation-center";
+export declare const CONNECTOR_NODE_KINDS: readonly ConnectorNodeKind[];
+export type LocalKnowledgeNodeTarget = {
+    readonly kind: "capsule";
+    readonly capsuleId: KnowledgeCapsuleId;
+} | {
+    readonly kind: "capsule-set";
+    readonly capsuleSetId: CapsuleSetId;
+};
+export type ConnectorNode = {
+    readonly kind: "files-window";
+    readonly nodeId: string;
+    readonly scope: KnowledgeSourceScope;
+} | {
+    readonly kind: "local-knowledge";
+    readonly nodeId: string;
+    readonly target: LocalKnowledgeNodeTarget;
+} | {
+    readonly kind: "conversation-center";
+    readonly nodeId: string;
+    readonly conversationId: string;
+    readonly route: string;
+};
+export interface ConnectorNodeRef {
+    readonly nodeId: string;
+    readonly kind: ConnectorNodeKind;
+}
+export interface ConnectorEdge {
+    readonly from: ConnectorNodeRef;
+    readonly to: ConnectorNodeRef;
+    readonly createdAt: number;
+}
+export interface ConnectorGraphState {
+    readonly schemaVersion: typeof LOCAL_KNOWLEDGE_SCHEMA_VERSION;
+    readonly nodes: readonly ConnectorNode[];
+    readonly edges: readonly ConnectorEdge[];
+    readonly updatedAt: number;
+}
+export {};
+//# sourceMappingURL=local-knowledge.d.ts.map

package/dist/local-knowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-knowledge.d.ts","sourceRoot":"","sources":["../src/local-knowledge.ts"],"names":[],"mappings":"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"}