@polpo-ai/core 0.15.47 → 0.15.49

package/dist/__tests__/brain-service.test.js

@@ -0,0 +1,193 @@
+import { describe, expect, it } from "vitest";
+import { BrainIngestionError, InMemoryBrainStore, PlainTextBrainParser, createBrainSource, createBrainSourceVersion, ingestBrainSource, readBrainSource, } from "../brain/index.js";
+const projectA = { kind: "project", subjectId: "project-a" };
+const projectB = { kind: "project", subjectId: "project-b" };
+const actor = {
+    actor: "agent",
+    actorId: "support",
+    agentName: "support",
+    projectId: "project-a",
+};
+const allow = {
+    authorize: async () => ({ allowed: true, reason: "test" }),
+};
+async function seed(store, input = {}) {
+    const scope = input.scope ?? projectA;
+    const sourceId = input.sourceId ?? "source-1";
+    const version = input.version ?? "v1";
+    await store.createSource(createBrainSource({
+        id: sourceId,
+        scope,
+        type: "paste",
+        label: "Runbook",
+        trust: "user_provided",
+    }, { now: () => "2026-07-28T12:00:00.000Z" }));
+    await store.createVersion(scope, createBrainSourceVersion({
+        sourceId,
+        version,
+    }, { now: () => "2026-07-28T12:00:00.000Z" }));
+    await ingestBrainSource({
+        ref: { scope, sourceId },
+        version,
+        body: {
+            kind: "text",
+            text: input.content ?? "Refunds are reviewed within five business days.",
+        },
+        contentType: "text/plain",
+        actor,
+    }, {
+        sourceStore: store,
+        versionStore: store,
+        chunkStore: store,
+        accessPolicy: allow,
+        parsers: [new PlainTextBrainParser()],
+        now: () => "2026-07-28T12:00:01.000Z",
+        maxChunkCharacters: 24,
+        overlapCharacters: 0,
+    });
+}
+describe("readBrainSource", () => {
+    it("reads the current indexed version with immutable citation-bearing chunks", async () => {
+        const store = new InMemoryBrainStore();
+        await seed(store);
+        const result = await readBrainSource({
+            ref: { scope: projectA, sourceId: "source-1" },
+            actor,
+        }, {
+            sourceStore: store,
+            versionStore: store,
+            chunkStore: store,
+            accessPolicy: allow,
+        });
+        expect(result.source.currentVersion).toBe("v1");
+        expect(result.version.version).toBe("v1");
+        expect(result.chunks.length).toBeGreaterThan(0);
+        expect(result.chunks[0].citation).toMatchObject({
+            sourceId: "source-1",
+            version: "v1",
+        });
+        expect(Object.isFrozen(result)).toBe(true);
+        expect(Object.isFrozen(result.chunks)).toBe(true);
+    });
+    it("requires an exact scope when identical source ids exist", async () => {
+        const store = new InMemoryBrainStore();
+        await seed(store, { scope: projectA, content: "Project A secret." });
+        await seed(store, { scope: projectB, content: "Project B secret." });
+        const result = await readBrainSource({
+            ref: { scope: projectA, sourceId: "source-1" },
+            actor,
+        }, {
+            sourceStore: store,
+            versionStore: store,
+            chunkStore: store,
+            accessPolicy: allow,
+        });
+        expect(result.chunks.map((chunk) => chunk.content).join(" ")).toContain("Project A");
+        expect(result.chunks.map((chunk) => chunk.content).join(" ")).not.toContain("Project B");
+    });
+    it("fails closed when access is denied or the policy throws", async () => {
+        const store = new InMemoryBrainStore();
+        await seed(store);
+        const policies = [
+            { authorize: async () => ({ allowed: false, reason: "denied" }) },
+            { authorize: async () => { throw new Error("policy unavailable"); } },
+        ];
+        for (const accessPolicy of policies) {
+            await expect(readBrainSource({
+                ref: { scope: projectA, sourceId: "source-1" },
+                actor,
+            }, {
+                sourceStore: store,
+                versionStore: store,
+                chunkStore: store,
+                accessPolicy,
+            })).rejects.toMatchObject({
+                code: "access_denied",
+            });
+        }
+    });
+    it("supports an explicit prior version without changing the visible version", async () => {
+        const store = new InMemoryBrainStore();
+        await seed(store, { version: "v1", content: "Original policy." });
+        await store.createVersion(projectA, createBrainSourceVersion({
+            sourceId: "source-1",
+            version: "v2",
+        }, { now: () => "2026-07-28T12:01:00.000Z" }));
+        await ingestBrainSource({
+            ref: { scope: projectA, sourceId: "source-1" },
+            version: "v2",
+            body: { kind: "text", text: "Updated policy." },
+            contentType: "text/plain",
+            actor,
+        }, {
+            sourceStore: store,
+            versionStore: store,
+            chunkStore: store,
+            accessPolicy: allow,
+            parsers: [new PlainTextBrainParser()],
+            now: () => "2026-07-28T12:01:01.000Z",
+        });
+        const prior = await readBrainSource({
+            ref: { scope: projectA, sourceId: "source-1" },
+            version: "v1",
+            actor,
+        }, {
+            sourceStore: store,
+            versionStore: store,
+            chunkStore: store,
+            accessPolicy: allow,
+        });
+        expect(prior.version.version).toBe("v1");
+        expect(prior.chunks.map((chunk) => chunk.content).join(" ")).toContain("Original policy");
+        await expect(store.getSource({
+            scope: projectA,
+            sourceId: "source-1",
+        })).resolves.toMatchObject({ currentVersion: "v2" });
+    });
+    it("applies offset, chunk limit, and token budget without partial chunks", async () => {
+        const store = new InMemoryBrainStore();
+        await seed(store, {
+            content: "alpha alpha alpha alpha beta beta beta beta gamma gamma gamma gamma",
+        });
+        const result = await readBrainSource({
+            ref: { scope: projectA, sourceId: "source-1" },
+            actor,
+            offset: 1,
+            limit: 2,
+            tokenBudget: 8,
+        }, {
+            sourceStore: store,
+            versionStore: store,
+            chunkStore: store,
+            accessPolicy: allow,
+        });
+        expect(result.chunks.length).toBeLessThanOrEqual(2);
+        expect(result.nextOffset === undefined || result.nextOffset > 1).toBe(true);
+    });
+    it("does not return content deleted while authorization is in flight", async () => {
+        const store = new InMemoryBrainStore();
+        await seed(store);
+        let release;
+        const waiting = new Promise((resolve) => { release = resolve; });
+        const policy = {
+            authorize: async () => {
+                await waiting;
+                return { allowed: true, reason: "test" };
+            },
+        };
+        const pending = readBrainSource({
+            ref: { scope: projectA, sourceId: "source-1" },
+            actor,
+        }, {
+            sourceStore: store,
+            versionStore: store,
+            chunkStore: store,
+            accessPolicy: policy,
+        });
+        await store.deleteSource({ scope: projectA, sourceId: "source-1" });
+        release();
+        await expect(pending).rejects.toBeInstanceOf(BrainIngestionError);
+        await expect(pending).rejects.toMatchObject({ code: "source_not_found" });
+    });
+});
+//# sourceMappingURL=brain-service.test.js.map

package/dist/__tests__/brain-service.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-service.test.js","sourceRoot":"","sources":["../../src/__tests__/brain-service.test.ts"],"names":[],"mappings":"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"}

package/dist/adapter.d.ts

@@ -9,6 +9,7 @@ import type { RuntimePlan } from "./runtime-plan/index.js";
 import type { RuntimeSandboxOptions } from "./runtime-sandbox.js";
 import type { RunOutputPolicy, RunToolMiddleware, RuntimeOutputEnforcementMode } from "./guardrails/index.js";
 import type { RuntimeContextResolution, RuntimeContextTrustMode, RuntimePromptContextSegment } from "./runtime-context/index.js";
+import type { BrainReadService, BrainServiceContext } from "./brain/index.js";
 /**
  * Handle returned by the engine after spawning an agent.
  * The orchestrator uses this to monitor and control the agent.
@@ -66,6 +67,10 @@ export interface SpawnContext {
     vaultStore?: VaultStore;
     /** Memory store — for agent-scoped memory_* tools. */
     memoryStore?: MemoryStore;
+    /** Scoped Brain reader — omitted when Brain is unavailable in this host. */
+    brainService?: BrainReadService;
+    /** Host-resolved Brain actor and scopes. Never supplied by the model. */
+    brainContext?: BrainServiceContext;
     /** FileSystem implementation — created by the orchestrator, passed down to tools. */
     fs?: FileSystem;
     /** Shell implementation — created by the orchestrator, passed down to tools. */

package/dist/adapter.d.ts.map

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

package/dist/brain/chunking.d.ts

@@ -0,0 +1,13 @@
+import type { BrainChunk, BrainParsedSection, BrainSource } from "./types.js";
+export declare const DEFAULT_BRAIN_CHUNK_CHARACTERS = 1600;
+export declare const DEFAULT_BRAIN_CHUNK_OVERLAP_CHARACTERS = 220;
+export interface ChunkBrainSectionsInput {
+    readonly source: BrainSource;
+    readonly version: string;
+    readonly sections: readonly BrainParsedSection[];
+    readonly maxCharacters?: number;
+    readonly overlapCharacters?: number;
+    readonly createId?: () => string;
+}
+export declare function chunkBrainSections(input: ChunkBrainSectionsInput): BrainChunk[];
+//# sourceMappingURL=chunking.d.ts.map

package/dist/brain/chunking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunking.d.ts","sourceRoot":"","sources":["../../src/brain/chunking.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAClB,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,8BAA8B,OAAQ,CAAC;AACpD,eAAO,MAAM,sCAAsC,MAAM,CAAC;AAE1D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACjD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC;CAClC;AAgDD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,uBAAuB,GAC7B,UAAU,EAAE,CA8Dd"}

package/dist/brain/chunking.js

@@ -0,0 +1,99 @@
+import { nanoid } from "nanoid";
+import { createBrainChunk } from "./contracts.js";
+import { BrainStoreValidationError } from "./store-errors.js";
+export const DEFAULT_BRAIN_CHUNK_CHARACTERS = 1_600;
+export const DEFAULT_BRAIN_CHUNK_OVERLAP_CHARACTERS = 220;
+function positiveInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new BrainStoreValidationError(`${name} must be a positive integer`);
+    }
+    return value;
+}
+function splitSection(content, maxCharacters, overlapCharacters) {
+    const normalized = content
+        .replace(/\r\n?/g, "\n")
+        .replace(/[ \t]+\n/g, "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+    if (!normalized)
+        return [];
+    const chunks = [];
+    let start = 0;
+    while (start < normalized.length) {
+        const hardEnd = Math.min(start + maxCharacters, normalized.length);
+        let end = hardEnd;
+        if (hardEnd < normalized.length) {
+            const minimumSoftBreak = start + Math.floor(maxCharacters * 0.55);
+            const candidates = [
+                normalized.lastIndexOf("\n\n", hardEnd),
+                normalized.lastIndexOf(". ", hardEnd),
+                normalized.lastIndexOf("\n", hardEnd),
+                normalized.lastIndexOf(" ", hardEnd),
+            ].filter((candidate) => candidate >= minimumSoftBreak);
+            if (candidates.length > 0) {
+                end = Math.max(...candidates);
+                if (normalized.slice(end, end + 2) === ". ")
+                    end += 1;
+            }
+        }
+        const chunk = normalized.slice(start, end).trim();
+        if (chunk)
+            chunks.push(chunk);
+        if (end >= normalized.length)
+            break;
+        const next = end - overlapCharacters;
+        start = Math.max(start + 1, next);
+    }
+    return chunks;
+}
+export function chunkBrainSections(input) {
+    const maxCharacters = positiveInteger(input.maxCharacters ?? DEFAULT_BRAIN_CHUNK_CHARACTERS, "maxCharacters");
+    const overlapCharacters = input.overlapCharacters
+        ?? DEFAULT_BRAIN_CHUNK_OVERLAP_CHARACTERS;
+    if (!Number.isSafeInteger(overlapCharacters)
+        || overlapCharacters < 0
+        || overlapCharacters >= maxCharacters) {
+        throw new BrainStoreValidationError("overlapCharacters must be a non-negative integer smaller than maxCharacters");
+    }
+    if (!Array.isArray(input.sections)) {
+        throw new BrainStoreValidationError("sections must be an array");
+    }
+    const uri = typeof input.source.metadata.uri === "string"
+        ? input.source.metadata.uri
+        : undefined;
+    const chunks = [];
+    for (const section of input.sections) {
+        if (!section || typeof section.content !== "string") {
+            throw new BrainStoreValidationError("Every parsed section must contain text");
+        }
+        const pieces = splitSection(section.content, maxCharacters, overlapCharacters);
+        for (const [pieceIndex, content] of pieces.entries()) {
+            const id = input.createId?.() ?? `brain-chunk-${nanoid(16)}`;
+            const locator = section.locator
+                ? `${section.locator} · chunk ${pieceIndex + 1}`
+                : `chunk ${chunks.length + 1}`;
+            chunks.push(createBrainChunk({
+                id,
+                sourceId: input.source.id,
+                version: input.version,
+                index: chunks.length,
+                content,
+                citation: {
+                    sourceId: input.source.id,
+                    version: input.version,
+                    chunkId: id,
+                    label: input.source.label,
+                    ...(uri ? { uri } : {}),
+                    locator,
+                    capturedAt: input.source.updatedAt,
+                },
+                tokenCount: Math.max(1, Math.ceil(content.length / 4)),
+                metadata: section.metadata
+                    ? { ...input.source.metadata, ...section.metadata }
+                    : { ...input.source.metadata },
+            }));
+        }
+    }
+    return chunks;
+}
+//# sourceMappingURL=chunking.js.map

package/dist/brain/chunking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunking.js","sourceRoot":"","sources":["../../src/brain/chunking.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAO9D,MAAM,CAAC,MAAM,8BAA8B,GAAG,KAAK,CAAC;AACpD,MAAM,CAAC,MAAM,sCAAsC,GAAG,GAAG,CAAC;AAW1D,SAAS,eAAe,CAAC,KAAa,EAAE,IAAY;IAClD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,yBAAyB,CAAC,GAAG,IAAI,6BAA6B,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,YAAY,CACnB,OAAe,EACf,aAAqB,EACrB,iBAAyB;IAEzB,MAAM,UAAU,GAAG,OAAO;SACvB,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC;SACvB,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC;SAC1B,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC;SAC1B,IAAI,EAAE,CAAC;IACV,IAAI,CAAC,UAAU;QAAE,OAAO,EAAE,CAAC;IAE3B,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;QACnE,IAAI,GAAG,GAAG,OAAO,CAAC;QAClB,IAAI,OAAO,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC;YAChC,MAAM,gBAAgB,GAAG,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;YAClE,MAAM,UAAU,GAAG;gBACjB,UAAU,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC;gBACvC,UAAU,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC;gBACrC,UAAU,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC;gBACrC,UAAU,CAAC,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC;aACrC,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,IAAI,gBAAgB,CAAC,CAAC;YACvD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC1B,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC;gBAC9B,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,CAAC,KAAK,IAAI;oBAAE,GAAG,IAAI,CAAC,CAAC;YACxD,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QAClD,IAAI,KAAK;YAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9B,IAAI,GAAG,IAAI,UAAU,CAAC,MAAM;YAAE,MAAM;QACpC,MAAM,IAAI,GAAG,GAAG,GAAG,iBAAiB,CAAC;QACrC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,KAA8B;IAE9B,MAAM,aAAa,GAAG,eAAe,CACnC,KAAK,CAAC,aAAa,IAAI,8BAA8B,EACrD,eAAe,CAChB,CAAC;IACF,MAAM,iBAAiB,GAAG,KAAK,CAAC,iBAAiB;WAC5C,sCAAsC,CAAC;IAC5C,IACE,CAAC,MAAM,CAAC,aAAa,CAAC,iBAAiB,CAAC;WACrC,iBAAiB,GAAG,CAAC;WACrB,iBAAiB,IAAI,aAAa,EACrC,CAAC;QACD,MAAM,IAAI,yBAAyB,CACjC,6EAA6E,CAC9E,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,yBAAyB,CAAC,2BAA2B,CAAC,CAAC;IACnE,CAAC;IACD,MAAM,GAAG,GAAG,OAAO,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,KAAK,QAAQ;QACvD,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG;QAC3B,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACrC,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YACpD,MAAM,IAAI,yBAAyB,CACjC,wCAAwC,CACzC,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAG,YAAY,CACzB,OAAO,CAAC,OAAO,EACf,aAAa,EACb,iBAAiB,CAClB,CAAC;QACF,KAAK,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;YACrD,MAAM,EAAE,GAAG,KAAK,CAAC,QAAQ,EAAE,EAAE,IAAI,eAAe,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;YAC7D,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO;gBAC7B,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,YAAY,UAAU,GAAG,CAAC,EAAE;gBAChD,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC;gBAC3B,EAAE;gBACF,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE;gBACzB,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,KAAK,EAAE,MAAM,CAAC,MAAM;gBACpB,OAAO;gBACP,QAAQ,EAAE;oBACR,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE;oBACzB,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,OAAO,EAAE,EAAE;oBACX,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK;oBACzB,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACvB,OAAO;oBACP,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,SAAS;iBACnC;gBACD,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;gBACtD,QAAQ,EAAE,OAAO,CAAC,QAAQ;oBACxB,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE;oBACnD,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,QAAQ,EAAE;aACjC,CAAC,CAAC,CAAC;QACN,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/brain/contracts.d.ts

@@ -0,0 +1,15 @@
+import { type BrainAccessDecision, type BrainChunk, type BrainCitation, type BrainFactoryOptions, type BrainIngestionJob, type BrainRetrievalResult, type BrainSource, type BrainSourceVersion, type CreateBrainChunkInput, type CreateBrainIngestionJobInput, type CreateBrainRetrievalResultInput, type CreateBrainSourceInput, type CreateBrainSourceVersionInput } from "./types.js";
+export declare const MAX_BRAIN_SOURCE_LABEL_CHARACTERS = 512;
+export declare const MAX_BRAIN_CHUNK_CONTENT_CHARACTERS = 128000;
+export declare function createBrainSource(input: CreateBrainSourceInput, factory?: BrainFactoryOptions): BrainSource;
+export declare function normalizeBrainSource(value: unknown): BrainSource;
+export declare function createBrainSourceVersion(input: CreateBrainSourceVersionInput, factory?: Pick<BrainFactoryOptions, "now">): BrainSourceVersion;
+export declare function normalizeBrainSourceVersion(value: unknown): BrainSourceVersion;
+export declare function normalizeBrainCitation(value: unknown): BrainCitation;
+export declare function createBrainChunk(input: CreateBrainChunkInput): BrainChunk;
+export declare function normalizeBrainChunk(value: unknown): BrainChunk;
+export declare function createBrainRetrievalResult(input: CreateBrainRetrievalResultInput): BrainRetrievalResult;
+export declare function createBrainIngestionJob(input: CreateBrainIngestionJobInput, factory?: BrainFactoryOptions): BrainIngestionJob;
+export declare function normalizeBrainIngestionJob(value: unknown): BrainIngestionJob;
+export declare function normalizeBrainAccessDecision(value: unknown): BrainAccessDecision;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/brain/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/brain/contracts.ts"],"names":[],"mappings":"AAGA,OAAO,EAOL,KAAK,mBAAmB,EACxB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EAGtB,KAAK,oBAAoB,EAEzB,KAAK,WAAW,EAGhB,KAAK,kBAAkB,EAGvB,KAAK,qBAAqB,EAC1B,KAAK,4BAA4B,EACjC,KAAK,+BAA+B,EACpC,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,EACnC,MAAM,YAAY,CAAC;AAapB,eAAO,MAAM,iCAAiC,MAAM,CAAC;AACrD,eAAO,MAAM,kCAAkC,SAAU,CAAC;AAgJ1D,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,sBAAsB,EAC7B,OAAO,GAAE,mBAAwB,GAChC,WAAW,CAuBb;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAQhE;AAsGD,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,6BAA6B,EACpC,OAAO,GAAE,IAAI,CAAC,mBAAmB,EAAE,KAAK,CAAM,GAC7C,kBAAkB,CA2BpB;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,GACb,kBAAkB,CAQpB;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CA0EpE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,UAAU,CAuDzE;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAQ9D;AAwCD,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,+BAA+B,GACrC,oBAAoB,CAkBtB;AAsKD,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,4BAA4B,EACnC,OAAO,GAAE,mBAAwB,GAChC,iBAAiB,CAsBnB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GACb,iBAAiB,CAQnB;AAED,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,OAAO,GACb,mBAAmB,CAkCrB"}