@sixb/core 0.1.21 → 0.1.22

package/dist/agents/types.d.ts

@@ -8,16 +8,27 @@ import type { ModelsRuntime } from "../models/generation-types";
 import type { InferSchema } from "../ontology/inference";
 import type { Schema } from "../ontology/types";
 import type { ObjectReader } from "../runtime/types";
+import type { UsersRuntime } from "../users";
 export type { AgentContextEntryInput, AgentContextInput, AgentContextOrigin, AgentContextPart, } from "./context/entries";
 /** Public capability reference used by security grants such as `can.run(agent)`. */
 export interface AgentReference {
     readonly kind: "agent";
     readonly usage: AgentUsageReference;
+    readonly threads: AgentThreadsReference;
+    readonly memory: AgentMemoryReference;
 }
 /** Project-wide AI accounting and limit capability, independent of permission to run the Agent. */
 export interface AgentUsageReference {
     readonly kind: "aiUsage";
 }
+/** Every user's conversations with the Agent, as `can.observe(agent.threads)` reads them. */
+export interface AgentThreadsReference {
+    readonly kind: "agentThreads";
+}
+/** The project's shared Agent memory, which every conversation reads. */
+export interface AgentMemoryReference {
+    readonly kind: "agentMemory";
+}
 /** Public metadata for the project's conversational Agent. */
 export interface AgentDescriptor {
     readonly name: string;
@@ -111,6 +122,7 @@ export interface AgentToolRuntimeFacade extends ObjectReader {
     readonly actions: ActionsRuntime;
     readonly models: ModelsRuntime;
     readonly connector: ConnectorRuntime;
+    readonly users: UsersRuntime;
 }
 /** The narrow, run-scoped surface passed to an agent tool handler. */
 export interface AgentToolRunContext<TInput extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> {
@@ -124,8 +136,8 @@ export interface AgentToolRunContext<TInput extends Readonly<Record<string, unkn
     readonly attachments: AgentToolAttachments;
 }
 /** Agent tool handlers may return only values safe to persist in agent messages. */
-export type AgentToolHandlerResult = ReadonlyJsonValue | AgentToolResult | Promise<ReadonlyJsonValue | AgentToolResult>;
-export type AgentToolHandler<TInput extends Readonly<Record<string, unknown>>> = (context: AgentToolRunContext<TInput>) => AgentToolHandlerResult;
+export type AgentToolHandlerResult<TOutput extends ReadonlyJsonValue | AgentToolResult = ReadonlyJsonValue | AgentToolResult> = TOutput | Promise<TOutput>;
+export type AgentToolHandler<TInput extends Readonly<Record<string, unknown>>, TOutput extends ReadonlyJsonValue | AgentToolResult = ReadonlyJsonValue | AgentToolResult> = (context: AgentToolRunContext<TInput>) => AgentToolHandlerResult<TOutput>;
 /**
  * Runtime definitions are stored heterogeneously. Keep variance erasure at this
  * boundary only; authoring through `run()` remains strictly contravariant.
@@ -133,18 +145,25 @@ export type AgentToolHandler<TInput extends Readonly<Record<string, unknown>>> =
 type StoredAgentToolHandler<TInput extends Readonly<Record<string, unknown>>> = {
     bivarianceHack(context: AgentToolRunContext<TInput>): JsonValue | Promise<JsonValue>;
 }["bivarianceHack"];
+declare const agentToolOutputValueType: unique symbol;
 /** A reusable, inert model tool definition selected explicitly by an agent. */
-export interface AgentToolDefinition<TName extends string = string, TInput extends AgentToolInputSchema = AgentToolInputSchema> {
+export interface AgentToolDefinition<TName extends string = string, TInput extends AgentToolInputSchema = AgentToolInputSchema, TOutput extends ReadonlyJsonValue | AgentToolResult = ReadonlyJsonValue | AgentToolResult> {
     readonly kind: "agentTool";
     readonly name: TName;
     readonly description: string;
     readonly input: TInput;
     readonly handler: StoredAgentToolHandler<InferAgentToolInputSchema<TInput>>;
+    readonly [agentToolOutputValueType]?: TOutput;
 }
 /** Infer the input received by a tool definition's handler. */
 export type InferAgentToolInput<TTool extends AgentToolDefinition> = InferAgentToolInputSchema<TTool["input"]>;
+/**
+ * Infer the output a chat receives from a tool: its handler's return value, saved on the message
+ * and streamed live as is. A file-aware tool's output is its `AgentToolResult` envelope.
+ */
+export type InferAgentToolOutput<TTool extends AgentToolDefinition> = TTool extends AgentToolDefinition<string, AgentToolInputSchema, infer TOutput> ? TOutput : never;
 export interface AgentToolRunBuilder<TName extends string, TInput extends AgentToolInputSchema> {
-    run(handler: AgentToolHandler<InferAgentToolInputSchema<TInput>>): AgentToolDefinition<TName, TInput>;
+    run<TOutput extends ReadonlyJsonValue | AgentToolResult>(handler: AgentToolHandler<InferAgentToolInputSchema<TInput>, TOutput>): AgentToolDefinition<TName, TInput, TOutput>;
 }
 export interface AgentToolInputBuilder<TName extends string> {
     input<const TInput extends AgentToolInputSchema>(input: TInput): AgentToolRunBuilder<TName, TInput>;

package/dist/agents/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAC1E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,EAAE,KAAK,gBAAgB,EAA0B,KAAK,cAAc,EAAE,MAAM,WAAW,CAAA;AAC9F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAE5C,YAAY,EACV,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,mBAAmB,CAAA;AAE1B,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAA;IACnC,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAA;IACvC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;CACtC;AAED,mGAAmG;AACnG,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CACzB;AAED,6FAA6F;AAC7F,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAC9B;AAED,yEAAyE;AACzE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAC7B;AAED,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAA;CACjC;AAED,MAAM,MAAM,cAAc,GAAG,cAAc,CAAA;AAE3C,eAAO,MAAM,sBAAsB,2FAAyB,CAAA;AAE5D,KAAK,QAAQ,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,EAAE,CAAA;AAChD,KAAK,qBAAqB,CAAC,CAAC,IAAI,OAAO,SAAS,CAAC,GAC7C,iBAAiB,GACjB,CAAC,SAAS,IAAI,GACZ,MAAM,GACN,CAAC,SAAS,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,GAChC,SAAS,qBAAqB,CAAC,KAAK,CAAC,EAAE,GACvC,CAAC,SAAS,aAAa,GACrB,CAAC,GACD,CAAC,SAAS,MAAM,GACd;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GACxD,KAAK,CAAA;AAEjB,oEAAoE;AACpE,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AAEnE,mEAAmE;AACnE,MAAM,MAAM,yBAAyB,CAAC,MAAM,SAAS,oBAAoB,IACvE,MAAM,SAAS,MAAM,MAAM,GACvB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACjC,QAAQ,CAAC;IACP,QAAQ,EAAE,CAAC,IAAI,MAAM,MAAM,GAAG,qBAAqB,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;CAC5E,CAAC,CAAA;AAER,6FAA6F;AAC7F,MAAM,MAAM,gBAAgB,GACxB;IACE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,CAAA;AAEL,8EAA8E;AAC9E,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,6FAA6F;AAC7F,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CAC1D;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;CACjD;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B,CAAA;AAED,kEAAkE;AAClE,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,GAAG,oBAAoB,CAAA;AAE1E;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAC9C,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,sBAAuB,SAAQ,YAAY;IAC1D,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAA;IACpC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;CAC7B;AAED,sEAAsE;AACtE,MAAM,WAAW,mBAAmB,CAClC,MAAM,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEpF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAA;IAC9B,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAA;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAC9B,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAA;CAC3C;AAED,oFAAoF;AACpF,MAAM,MAAM,sBAAsB,CAChC,OAAO,SAAS,iBAAiB,GAAG,eAAe,GAAG,iBAAiB,GAAG,eAAe,IACvF,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;AAE9B,MAAM,MAAM,gBAAgB,CAC1B,MAAM,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAChD,OAAO,SAAS,iBAAiB,GAAG,eAAe,GAAG,iBAAiB,GAAG,eAAe,IACvF,CAAC,OAAO,EAAE,mBAAmB,CAAC,MAAM,CAAC,KAAK,sBAAsB,CAAC,OAAO,CAAC,CAAA;AAE7E;;;GAGG;AACH,KAAK,sBAAsB,CAAC,MAAM,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI;IAC9E,cAAc,CAAC,OAAO,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;CACrF,CAAC,gBAAgB,CAAC,CAAA;AAEnB,OAAO,CAAC,MAAM,wBAAwB,EAAE,OAAO,MAAM,CAAA;AAErD,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB,CAClC,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,MAAM,SAAS,oBAAoB,GAAG,oBAAoB,EAC1D,OAAO,SAAS,iBAAiB,GAAG,eAAe,GAAG,iBAAiB,GAAG,eAAe;IAEzF,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC,yBAAyB,CAAC,MAAM,CAAC,CAAC,CAAA;IAC3E,QAAQ,CAAC,CAAC,wBAAwB,CAAC,CAAC,EAAE,OAAO,CAAA;CAC9C;AAED,+DAA+D;AAC/D,MAAM,MAAM,mBAAmB,CAAC,KAAK,SAAS,mBAAmB,IAAI,yBAAyB,CAC5F,KAAK,CAAC,OAAO,CAAC,CACf,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAAC,KAAK,SAAS,mBAAmB,IAChE,KAAK,SAAS,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC,GAAG,OAAO,GAAG,KAAK,CAAA;AAElG,MAAM,WAAW,mBAAmB,CAAC,KAAK,SAAS,MAAM,EAAE,MAAM,SAAS,oBAAoB;IAC5F,GAAG,CAAC,OAAO,SAAS,iBAAiB,GAAG,eAAe,EACrD,OAAO,EAAE,gBAAgB,CAAC,yBAAyB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,GACpE,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/C;AAED,MAAM,WAAW,qBAAqB,CAAC,KAAK,SAAS,MAAM;IACzD,KAAK,CAAC,KAAK,CAAC,MAAM,SAAS,oBAAoB,EAC7C,KAAK,EAAE,MAAM,GACZ,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;CACtC;AAED,MAAM,WAAW,2BAA2B,CAAC,KAAK,SAAS,MAAM;IAC/D,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAA;CAC/D"}

package/dist/agents/validation.d.ts

@@ -1,7 +1,7 @@
 import { type JsonValue } from "../json";
 import { type ValueType } from "../ontology";
 import type { AgentToolDefinition, AgentToolInputSchema } from "./types";
-export declare const AGENT_RESERVED_TOOL_NAMES: readonly ["bash", "read", "view_file", "spawn_agent", "wait_agent", "publish_artifact", "publish_artifact_version"];
+export declare const AGENT_RESERVED_TOOL_NAMES: readonly ["bash", "read", "view_file", "spawn_agent", "wait_agent", "message_agent", "ask_parent", "publish_artifact", "publish_artifact_version"];
 export declare function isAgentToolDefinition(value: unknown): value is AgentToolDefinition;
 export declare function assertValidAgentToolName(name: unknown): asserts name is string;
 export declare function assertValidAgentToolDescription(name: string, description: unknown): void;

package/dist/agents/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/agents/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4C,KAAK,SAAS,EAAE,MAAM,SAAS,CAAA;AAClF,OAAO,EAA8C,KAAK,SAAS,EAAE,MAAM,aAAa,CAAA;AAKxF,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAGxE,eAAO,MAAM,yBAAyB,qHAQ5B,CAAA;AAEV,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CASlF;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAS9E;AAED,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,IAAI,CAIxF;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAa5E;AAED,wBAAgB,iCAAiC,CAAC,MAAM,SAAS,oBAAoB,EACnF,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,MAAM,CASR;AAED,+FAA+F;AAC/F,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,oBAAoB,EAC3B,KAAK,EAAE,OAAO,EACd,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,GAC7C,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAwB3B;AAQD,wBAAgB,sCAAsC,CACpD,KAAK,EAAE,SAAS,mBAAmB,EAAE,GACpC,IAAI,CAoBN"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/agents/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4C,KAAK,SAAS,EAAE,MAAM,SAAS,CAAA;AAClF,OAAO,EAA8C,KAAK,SAAS,EAAE,MAAM,aAAa,CAAA;AAKxF,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAGxE,eAAO,MAAM,yBAAyB,oJAU5B,CAAA;AAEV,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CASlF;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAS9E;AAED,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,IAAI,CAIxF;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAa5E;AAED,wBAAgB,iCAAiC,CAAC,MAAM,SAAS,oBAAoB,EACnF,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,MAAM,CASR;AAED,+FAA+F;AAC/F,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,oBAAoB,EAC3B,KAAK,EAAE,OAAO,EACd,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,GAC7C,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAwB3B;AAQD,wBAAgB,sCAAsC,CACpD,KAAK,EAAE,SAAS,mBAAmB,EAAE,GACpC,IAAI,CAoBN"}

package/dist/artifacts/access.d.ts

@@ -0,0 +1,52 @@
+import { type Principal } from "../auth";
+import type { ArtifactRecord, ArtifactStorage } from "../storage/artifacts/types";
+/**
+ * What the caller may do with an artifact.
+ *
+ * - `owner`: everything, deleting it included.
+ * - `update`: read every version and publish the next one, as the owner or a participant of a
+ *   conversation that shares it.
+ * - `read`: read every version, as someone who observes a conversation that shares it.
+ * - `none`: nothing; the artifact exists but is not shared with the caller.
+ */
+export type ArtifactAccess = "owner" | "update" | "read" | "none";
+/** How the caller reads a conversation: talking in it, only observing it, or not at all. */
+export type ConversationAccess = "update" | "read" | null;
+/**
+ * The one rule for who reaches an artifact.
+ *
+ * Its owner reaches it, and code without a caller reaches every artifact. Anyone else reaches an
+ * artifact shared in a conversation they read: one the Agent published a version in, or a fork
+ * of it copied. Whoever owns or takes part in that conversation may update the artifact; an
+ * observer of it only reads. The artifact is shared whole, at every version, whatever published
+ * each one. Only a signed-in session reaches what is shared: an access token, or a principal
+ * without a credential, reaches only its own artifacts.
+ *
+ * A rule reads how the caller reads each conversation once, so it lives for one operation.
+ */
+export interface ArtifactAccessRule {
+    accessTo(artifact: ArtifactRecord): Promise<ArtifactAccess>;
+    /**
+     * What the caller may do when publishing the artifact's next version from a conversation, or
+     * outside any without `threadId`. Its owner publishes from anywhere, and a version published in
+     * a conversation shares the artifact there: that is how sharing starts. Anyone else publishes
+     * from a conversation only when it already shares the artifact, with the access they have there,
+     * so a version never shares someone else's artifact in another conversation.
+     */
+    publishAccess(artifact: ArtifactRecord, threadId?: string): Promise<ArtifactAccess>;
+    /** How the caller reads the artifacts a conversation shares. */
+    conversation(threadId: string): Promise<ConversationAccess>;
+}
+export declare function createArtifactAccessRule(input: {
+    readonly storage: ArtifactStorage;
+    readonly projectId: string;
+    /** `system` for code without a caller, `null` for a caller that reaches no artifact. */
+    readonly caller: Principal | "system" | null;
+    /** `false` unless the caller signed in with a session: anything else reaches only its own. */
+    readonly sharing: boolean;
+    /** How the caller reads a conversation, by the thread-access rule. */
+    readonly conversation: (threadId: string) => Promise<ConversationAccess>;
+}): ArtifactAccessRule;
+/** Refuses an artifact the caller may not update: `not_shared`, or `read_only` for an observer. */
+export declare function assertUpdatable(artifactId: string, access: ArtifactAccess): void;
+//# sourceMappingURL=access.d.ts.map

package/dist/artifacts/access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../../src/artifacts/access.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAmB,MAAM,SAAS,CAAA;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAGjF;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAA;AAEjE,4FAA4F;AAC5F,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,MAAM,GAAG,IAAI,CAAA;AAEzD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IAC3D;;;;;;OAMG;IACH,aAAa,CAAC,QAAQ,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IACnF,gEAAgE;IAChE,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;CAC5D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,IAAI,CAAA;IAC5C,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,sEAAsE;IACtE,QAAQ,CAAC,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAA;CACzE,GAAG,kBAAkB,CAsDrB;AAED,mGAAmG;AACnG,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAchF"}

package/dist/artifacts/canvas.d.ts

@@ -0,0 +1,92 @@
+import { type ArtifactTone } from "./tones";
+/**
+ * A canvas artifact is `canvas.json`, its items on an endless board, and the HTML files its boards
+ * show beside it. Items draw in the order listed, sections behind everything else.
+ */
+export declare const CANVAS_FILE = "canvas.json";
+export declare const CANVAS_ITEM_TYPES: readonly ["board", "section", "note", "text", "shape", "arrow", "embed"];
+export type CanvasItemType = (typeof CANVAS_ITEM_TYPES)[number];
+export declare const CANVAS_SHAPES: readonly ["rect", "ellipse", "diamond"];
+export type CanvasShape = (typeof CANVAS_SHAPES)[number];
+export declare const CANVAS_TEXT_SIZES: readonly ["s", "m", "l", "xl"];
+export type CanvasTextSize = (typeof CANVAS_TEXT_SIZES)[number];
+/** Where an item sits, from the canvas's origin, in pixels; and how large it is. */
+interface Placed {
+    readonly id: string;
+    readonly x: number;
+    readonly y: number;
+}
+interface Sized extends Placed {
+    readonly w: number;
+    readonly h: number;
+}
+/** An HTML file of the canvas, shown live as a page `w` by `h`: a screen, a mockup, a poster. */
+export interface CanvasBoard extends Sized {
+    readonly type: "board";
+    readonly file: string;
+    readonly title?: string;
+}
+/** A titled region drawn behind what it holds: a flow, a cluster of notes. */
+export interface CanvasSection extends Sized {
+    readonly type: "section";
+    readonly title?: string;
+}
+/** A sticky note of plain text; its height follows its text unless it is given one. */
+export interface CanvasNote extends Placed {
+    readonly type: "note";
+    readonly w: number;
+    readonly h?: number;
+    readonly text: string;
+    readonly tone?: ArtifactTone;
+}
+/** A label or a heading on the canvas, wrapped at `w` when given. */
+export interface CanvasText extends Placed {
+    readonly type: "text";
+    readonly text: string;
+    readonly size: CanvasTextSize;
+    readonly w?: number;
+}
+/** A rectangle, ellipse, or diamond, with text inside: for diagrams. */
+export interface CanvasShapeItem extends Sized {
+    readonly type: "shape";
+    readonly shape: CanvasShape;
+    readonly text?: string;
+    readonly tone?: ArtifactTone;
+}
+/** Another artifact, or a part of one, shown in place: a chart, a range, a slide, a page. */
+export interface CanvasEmbed extends Sized {
+    readonly type: "embed";
+    readonly src: string;
+    readonly title?: string;
+}
+/** One end of an arrow: an item, by its id, or a point on the canvas. */
+export type CanvasEnd = string | {
+    readonly x: number;
+    readonly y: number;
+};
+/** An arrow from one item, or point, to another. */
+export interface CanvasArrow {
+    readonly id: string;
+    readonly type: "arrow";
+    readonly from: CanvasEnd;
+    readonly to: CanvasEnd;
+    readonly label?: string;
+    readonly dashed: boolean;
+}
+export type CanvasItem = CanvasBoard | CanvasSection | CanvasNote | CanvasText | CanvasShapeItem | CanvasEmbed | CanvasArrow;
+/** A canvas's items. It opens fitted to all of them. */
+export interface Canvas {
+    readonly items: readonly CanvasItem[];
+}
+/**
+ * Reads `canvas.json` into its full form, with defaults filled, or says what is wrong in words the
+ * author can act on, naming the item and the key. Whether a board's file exists is checked against
+ * the version's files.
+ */
+export declare function parseCanvas(text: string): {
+    readonly canvas: Canvas;
+} | {
+    readonly error: string;
+};
+export {};
+//# sourceMappingURL=canvas.d.ts.map

package/dist/artifacts/canvas.d.ts.map

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

package/dist/artifacts/csv.d.ts

@@ -19,4 +19,9 @@ export declare class CsvParseError extends Error {
 export declare function parseCsv(text: string, options?: {
     readonly delimiter?: "," | "\t";
 }): CsvTable;
+/**
+ * A table as CSV, the inverse of {@link parseCsv}: a field holding a comma, a quote, or a line
+ * break is quoted, its quotes doubled; lines end in CRLF, as RFC 4180 writes them.
+ */
+export declare function formatCsv(header: readonly string[], rows: readonly (readonly string[])[]): string;
 //# sourceMappingURL=csv.d.ts.map

package/dist/artifacts/csv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"csv.d.ts","sourceRoot":"","sources":["../../src/artifacts/csv.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAA;CAC9C;AAED,qBAAa,aAAc,SAAQ,KAAK;IAGpC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAFrB,OAAO,EAAE,MAAM;IACf,wEAAwE;IAC/D,IAAI,EAAE,MAAM;CAKxB;AAED,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;CAAO,GAChD,QAAQ,CAiFV"}
+{"version":3,"file":"csv.d.ts","sourceRoot":"","sources":["../../src/artifacts/csv.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAA;CAC9C;AAED,qBAAa,aAAc,SAAQ,KAAK;IAGpC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAFrB,OAAO,EAAE,MAAM;IACf,wEAAwE;IAC/D,IAAI,EAAE,MAAM;CAKxB;AAED,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;CAAO,GAChD,QAAQ,CAiFV;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,GAAG,MAAM,CAIjG"}

package/dist/artifacts/errors.d.ts

@@ -1,11 +1,16 @@
-export type ArtifactRequestErrorCode = "artifact_not_found" | "artifact_kind_mismatch" | "invalid_artifact" | "not_allowed" | "storage_unavailable";
+import type { ArtifactLatestVersion } from "../storage/artifacts/errors";
+export type ArtifactRequestErrorCode = "artifact_not_found" | "artifact_kind_mismatch" | "artifact_moved" | "invalid_artifact" | "invalid_state" | "state_full" | "not_allowed" | "not_shared" | "query_invalid" | "query_not_found" | "read_only" | "storage_unavailable";
 /**
  * Error for an artifact request the caller can correct or must be told about. Callers branch on
  * `code`; the message says what to change.
  */
 export declare class ArtifactRequestError extends Error {
     readonly code: ArtifactRequestErrorCode;
+    /** With `artifact_moved`: the latest version, which the publish was not based on. */
+    readonly latest?: ArtifactLatestVersion | undefined;
     readonly name = "ArtifactRequestError";
-    constructor(code: ArtifactRequestErrorCode, message: string);
+    constructor(code: ArtifactRequestErrorCode, message: string, 
+    /** With `artifact_moved`: the latest version, which the publish was not based on. */
+    latest?: ArtifactLatestVersion | undefined);
 }
 //# sourceMappingURL=errors.d.ts.map

package/dist/artifacts/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/artifacts/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,wBAAwB,GAChC,oBAAoB,GACpB,wBAAwB,GACxB,kBAAkB,GAClB,aAAa,GACb,qBAAqB,CAAA;AAEzB;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAI3C,QAAQ,CAAC,IAAI,EAAE,wBAAwB;IAHzC,QAAQ,CAAC,IAAI,0BAAyB;gBAG3B,IAAI,EAAE,wBAAwB,EACvC,OAAO,EAAE,MAAM;CAIlB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/artifacts/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAA;AAExE,MAAM,MAAM,wBAAwB,GAChC,oBAAoB,GACpB,wBAAwB,GACxB,gBAAgB,GAChB,kBAAkB,GAClB,eAAe,GACf,YAAY,GACZ,aAAa,GACb,YAAY,GACZ,eAAe,GACf,iBAAiB,GACjB,WAAW,GACX,qBAAqB,CAAA;AAEzB;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAI3C,QAAQ,CAAC,IAAI,EAAE,wBAAwB;IAEvC,qFAAqF;IACrF,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB;IANzC,QAAQ,CAAC,IAAI,0BAAyB;gBAG3B,IAAI,EAAE,wBAAwB,EACvC,OAAO,EAAE,MAAM;IACf,qFAAqF;IAC5E,MAAM,CAAC,EAAE,qBAAqB,YAAA;CAI1C"}

package/dist/artifacts/execution.d.ts

@@ -1,17 +1,54 @@
 import type { BlobStorage } from "../blob-storage/types";
+import type { ObjectQuery } from "../objects/query/ir";
+import type { PropertyToken } from "../ontology/tokens";
 import type { SixbRuntimeContext } from "../runtime/types";
 import type { ArtifactFile, ArtifactRecord, ArtifactVersionRecord, ListArtifactsResult, ListArtifactVersionsResult } from "../storage/artifacts/types";
+import type { Storage } from "../storage/types";
+import { type ArtifactAccess, type ArtifactAccessRule } from "./access";
 import type { ArtifactKind } from "./kinds";
 import { type PublishedArtifact } from "./publish/publish";
+import { type ArtifactQueryChecker } from "./publish/queries";
+import { type ArtifactQueryResult } from "./queries";
 /** A version's content: what its kind renders from, and what it is called. */
 export interface ArtifactContentInput {
     readonly kind: ArtifactKind;
     readonly title: string;
     /** Files stored with `sixb.blobs.put()` or `POST /api/files`, at their paths in the artifact. */
     readonly files: readonly ArtifactFile[];
+    /**
+     * Queries the version holds, by name, each stored as `queries/<name>.json` beside `files` and
+     * checked as those files are. Each reader runs them with their own rights.
+     */
+    readonly queries?: Readonly<Record<string, ArtifactQueryInput>>;
+}
+/**
+ * A query a version holds, from the query builders: `sixb.objects(Invoice).where(...)` for rows,
+ * or such a query with the properties to facet its rows by. Any builder fits: its `ir` is what
+ * the version keeps.
+ */
+export type ArtifactQueryInput = {
+    readonly ir: ObjectQuery;
+} | {
+    readonly query: {
+        readonly ir: ObjectQuery;
+    };
+    readonly facets: readonly {
+        readonly property: PropertyToken;
+        readonly limit: number;
+    }[];
+};
+export interface PublishArtifactRuntimeInput extends ArtifactContentInput {
+    /**
+     * The version this one was made from, such as the one a person edited. When another version was
+     * published since, publishing fails with `artifact_moved`, naming the latest and its author.
+     */
+    readonly baseVersion?: number;
 }
 export interface ListArtifactsRuntimeInput {
-    /** Only artifacts with a version the Agent published in this thread. */
+    /**
+     * Only the artifacts a conversation shares: every one of them, whoever owns it, for whoever reads
+     * the conversation; otherwise the caller's own among them.
+     */
     readonly threadId?: string;
     /** Only artifacts of this kind. */
     readonly kind?: ArtifactKind;
@@ -19,25 +56,83 @@ export interface ListArtifactsRuntimeInput {
     readonly offset?: number;
 }
 /**
- * Artifacts the caller owns: create one, publish its next version, read it back. A user or service
- * account reaches only its own artifacts; system code reaches every artifact in the project.
+ * The artifacts the caller reaches: its own, and those shared in a conversation it reads, as
+ * {@link ArtifactAccess} says. System code reaches every artifact in the project, and an access
+ * token only its own.
  */
 export interface ArtifactsRuntime {
     /** Creates an artifact owned by the caller, with its first version. */
     create(input: ArtifactContentInput): Promise<PublishedArtifact>;
-    /** Publishes the next version. The kind must be the artifact's. */
-    publish(artifactId: string, input: ArtifactContentInput): Promise<PublishedArtifact>;
+    /**
+     * Publishes the next version, authored by the caller; the artifact keeps its owner. The kind must
+     * be the artifact's. Throws `not_shared` or `read_only` when the caller may not update it.
+     */
+    publish(artifactId: string, input: PublishArtifactRuntimeInput): Promise<PublishedArtifact>;
+    /** What the caller may do with the artifact; `null` when there is no such artifact. */
+    access(artifactId: string): Promise<ArtifactAccess | null>;
+    /** `null` when the caller cannot read it. */
     get(artifactId: string): Promise<ArtifactRecord | null>;
     /** Most recently updated first. */
     list(input?: ListArtifactsRuntimeInput): Promise<ListArtifactsResult>;
     getVersion(artifactId: string, version: number | "latest"): Promise<ArtifactVersionRecord | null>;
-    /** Newest first; `null` when the artifact is not the caller's. */
+    /**
+     * Runs the version's query `queries/<name>.json` as the caller, with their rights: a type they
+     * cannot view refuses it, and a marked property they are not cleared for is left out of each
+     * row. Whoever reads the artifact runs its queries, an observer too. `null` when the caller
+     * cannot read the artifact or it has no such version. Throws `query_not_found`, and
+     * `query_invalid` for a query the ontology no longer admits.
+     */
+    query(artifactId: string, name: string, options?: {
+        readonly version?: number | "latest";
+    }): Promise<ArtifactQueryResult | null>;
+    /** Newest first; `null` when the caller cannot read the artifact. */
     listVersions(artifactId: string, input?: {
         readonly limit?: number;
         readonly offset?: number;
     }): Promise<ListArtifactVersionsResult | null>;
-    /** Deletes the artifact with every version. `false` when it is not the caller's. */
+    /**
+     * Deletes the artifact with every version, from every conversation that shares it; only its
+     * owner can. `false` when the caller does not own it.
+     */
     delete(artifactId: string): Promise<boolean>;
+    /**
+     * What the artifact keeps for the caller as its reader, as a page keeps it with `sixb.state`:
+     * JSON values by key, across its versions. Each reader who may update the artifact keeps their
+     * own. Each call throws `artifact_not_found`, `not_shared`, or `read_only` for an observer.
+     */
+    state(artifactId: string): ArtifactStateRuntime;
+}
+/** One reader's values, kept by one artifact. */
+export interface ArtifactStateRuntime {
+    /** The value under the key, or undefined when there is none. */
+    get(key: string): Promise<unknown>;
+    /**
+     * Keeps a JSON value under the key, replacing one there. Throws `invalid_state` for a key or a
+     * value that is not one, and `state_full` past `ARTIFACT_STATE_LIMITS`. Returns what it kept.
+     */
+    set(key: string, value: unknown): Promise<ArtifactStateValue>;
+    /** `false` when there was no value under the key. */
+    delete(key: string): Promise<boolean>;
+    /** Every value, by key in order. */
+    entries(): Promise<ArtifactStateValue[]>;
+    /** Deletes every value, and returns how many. */
+    clear(): Promise<number>;
 }
+export interface ArtifactStateValue {
+    readonly key: string;
+    readonly value: unknown;
+    readonly updatedAt: Date;
+}
+/** Where an access rule reads: the project's storage, or a transaction's to decide inside it. */
+export type ArtifactAccessStorage = Pick<Storage, "artifacts" | "agents">;
+/**
+ * The access rule of the caller `artifacts` acts for, reading from `storage`: a transaction's, to
+ * check inside it. Each call returns a rule of its own.
+ */
+export declare function artifactAccessRule(artifacts: Partial<ArtifactsRuntime>, storage: ArtifactAccessStorage): ArtifactAccessRule;
+/** What checks a version's queries as the caller `artifacts` acts for. */
+export declare function artifactQueryChecker(artifacts: Partial<ArtifactsRuntime>): ArtifactQueryChecker;
+/** The access rule for the runtime's caller, reading from `storage`. */
+export declare function createRuntimeArtifactAccessRule(runtime: SixbRuntimeContext, storage?: ArtifactAccessStorage): ArtifactAccessRule;
 export declare function createArtifactsRuntime(runtime: SixbRuntimeContext, blobStorage: BlobStorage): ArtifactsRuntime;
 //# sourceMappingURL=execution.d.ts.map

package/dist/artifacts/execution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../../src/artifacts/execution.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EAEd,qBAAqB,EACrB,mBAAmB,EACnB,0BAA0B,EAC3B,MAAM,4BAA4B,CAAA;AAEnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC3C,OAAO,EAAE,KAAK,iBAAiB,EAAmB,MAAM,mBAAmB,CAAA;AAE3E,8EAA8E;AAC9E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,iGAAiG;IACjG,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CACxC;AAED,MAAM,WAAW,yBAAyB;IACxC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,mCAAmC;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAA;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,MAAM,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAC/D,mEAAmE;IACnE,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;IACpF,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAA;IACvD,mCAAmC;IACnC,IAAI,CAAC,KAAK,CAAC,EAAE,yBAAyB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAA;IACrE,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAA;IACjG,kEAAkE;IAClE,YAAY,CACV,UAAU,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5D,OAAO,CAAC,0BAA0B,GAAG,IAAI,CAAC,CAAA;IAC7C,oFAAoF;IACpF,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC7C;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,kBAAkB,EAC3B,WAAW,EAAE,WAAW,GACvB,gBAAgB,CAuFlB"}
+{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../../src/artifacts/execution.ts"],"names":[],"mappings":"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"}

package/dist/artifacts/formula/check.d.ts

@@ -0,0 +1,24 @@
+import type { FormulaNode } from "./parser";
+/**
+ * What a formula yields, as far as its operands say: a date is a number of days that reads as a
+ * date, and `any` is a value whose kind depends on the row, such as an IF's two kinds of branch.
+ */
+export type FormulaType = "number" | "date" | "text" | "boolean" | "any";
+/** Every function a formula may call, with how many arguments it takes. */
+export declare const FORMULA_FUNCTIONS: Readonly<Record<string, {
+    readonly min: number;
+    readonly max: number;
+}>>;
+/** The functions that read a whole column, `[Name]`, and reduce it to one value. */
+export declare const AGGREGATE_FUNCTIONS: ReadonlySet<string>;
+/**
+ * Checks a formula against the columns its sheet has, each by what its values are: what it yields,
+ * or what is wrong with it, in words an author can act on. Text where a number is needed is
+ * refused here rather than computed to `#VALUE!` in every row.
+ */
+export declare function checkFormula(node: FormulaNode, columns: ReadonlyMap<string, FormulaType>): {
+    readonly type: FormulaType;
+} | {
+    readonly error: string;
+};
+//# sourceMappingURL=check.d.ts.map

package/dist/artifacts/formula/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../src/artifacts/formula/check.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAE3C;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,KAAK,CAAA;AAExE,2EAA2E;AAC3E,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CACtC,MAAM,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAsB/D,CAAA;AAED,oFAAoF;AACpF,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAMlD,CAAA;AAEF;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,GACxC;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAO7D"}

package/dist/artifacts/formula/evaluate.d.ts

@@ -0,0 +1,32 @@
+import type { FormulaNode } from "./parser";
+/** What a cell computes to when it can't: a division by zero, or a value of the wrong kind. */
+export declare const FORMULA_ERRORS: readonly ["#DIV/0!", "#VALUE!"];
+export type FormulaErrorCode = (typeof FORMULA_ERRORS)[number];
+/**
+ * A value as a formula sees it: a number (a date is its day count, as in Excel), text, a boolean,
+ * a blank, or an error that passes through everything but IFERROR.
+ */
+export type FormulaValue = number | string | boolean | null | {
+    readonly error: FormulaErrorCode;
+};
+/** The values a formula reads: this row's in a column, or a whole column's. */
+export interface FormulaScope {
+    readonly cell: (column: string) => FormulaValue;
+    readonly column: (column: string) => readonly FormulaValue[];
+}
+/**
+ * Evaluates a formula for one row, with Excel's rules: a blank reads as 0 in arithmetic and as
+ * empty text in `&`; booleans count as 1 and 0; text that reads as a number is one; text compares
+ * without regard to case, and number < text < boolean across kinds. An aggregate over whole
+ * columns is the same for every row, so `memo` keeps it once computed.
+ */
+export declare function evaluateFormula(node: FormulaNode, scope: FormulaScope, memo?: Map<FormulaNode, FormulaValue>): FormulaValue;
+/** A value as text: a number as Excel's General format writes it, a boolean as TRUE or FALSE. */
+export declare function formulaText(value: Exclude<FormulaValue, {
+    error: unknown;
+}>): string;
+/** A date as Excel's day count. */
+export declare function dateSerial(date: Date): number;
+/** A day count as the date it is: `2026-09-30`, or with its time when it has one. */
+export declare function serialDate(serial: number): string;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/artifacts/formula/evaluate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../../src/artifacts/formula/evaluate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAE3C,+FAA+F;AAC/F,eAAO,MAAM,cAAc,iCAAkC,CAAA;AAC7D,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA;AAE9D;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,CAAA;AAElG,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,YAAY,CAAA;IAC/C,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,SAAS,YAAY,EAAE,CAAA;CAC7D;AAMD;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,YAAY,EACnB,IAAI,GAAE,GAAG,CAAC,WAAW,EAAE,YAAY,CAAa,GAC/C,YAAY,CA6Bd;AAmBD,iGAAiG;AACjG,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,YAAY,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,GAAG,MAAM,CAKpF;AA0ED,mCAAmC;AACnC,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE7C;AAED,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIjD"}

package/dist/artifacts/formula/index.d.ts

@@ -0,0 +1,38 @@
+import type { CsvTable } from "../csv";
+import { type SheetColumnType, type WorkbookSheet } from "../workbook";
+import type { FormulaType } from "./check";
+import { type FormulaErrorCode } from "./evaluate";
+export { AGGREGATE_FUNCTIONS, checkFormula, FORMULA_FUNCTIONS, type FormulaType, } from "./check";
+export { FORMULA_ERRORS, type FormulaErrorCode, type FormulaValue, } from "./evaluate";
+export { type FormulaNode, type FormulaOperator, FormulaSyntaxError, formulaDependencies, formulaReferences, parseFormula, renameColumnReferences, } from "./parser";
+/** What a column's values are, as a formula reads them. */
+export declare function columnFormulaType(type: SheetColumnType): FormulaType;
+/**
+ * Whether what a formula yields can fill a column of a type: numbers in a number, currency, or
+ * percent column, dates in a date column, booleans in a boolean one, anything in text or a tag.
+ * A value whose kind depends on the row fits anywhere, and is `#VALUE!` where it doesn't.
+ */
+export declare function formulaFitsColumn(result: FormulaType, type: SheetColumnType): boolean;
+/** Computed columns that read each other in a ring, so none can be computed first. */
+export declare class FormulaCycleError extends Error {
+    readonly columns: readonly string[];
+    constructor(columns: readonly string[]);
+}
+/** Where a computed column computes to an error: how many rows, and the first. */
+export interface ComputedColumnErrors {
+    readonly count: number;
+    /** The first row, as the data row's index from 0. */
+    readonly firstRow: number;
+    readonly code: FormulaErrorCode;
+}
+/**
+ * A sheet's table with its computed columns filled in, each in an order that computes what it
+ * reads first, its values written as the column's type stores them. Throws a
+ * {@link FormulaCycleError} for columns that read each other; publishing has refused those, and
+ * every formula that doesn't parse or check.
+ */
+export declare function evaluateComputedColumns(sheet: Pick<WorkbookSheet, "columns">, table: CsvTable): {
+    readonly table: CsvTable;
+    readonly errors: ReadonlyMap<string, ComputedColumnErrors>;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/artifacts/formula/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/artifacts/formula/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,aAAa,EACnB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAC1C,OAAO,EAGL,KAAK,gBAAgB,EAItB,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,iBAAiB,EACjB,KAAK,WAAW,GACjB,MAAM,SAAS,CAAA;AAChB,OAAO,EACL,cAAc,EACd,KAAK,gBAAgB,EACrB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,EACZ,sBAAsB,GACvB,MAAM,UAAU,CAAA;AAEjB,2DAA2D;AAC3D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,CAIpE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAMrF;AAED,sFAAsF;AACtF,qBAAa,iBAAkB,SAAQ,KAAK;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE;gBAA1B,OAAO,EAAE,SAAS,MAAM,EAAE;CAIhD;AAED,kFAAkF;AAClF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,EACrC,KAAK,EAAE,QAAQ,GACd;IAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAA;CAAE,CA0D1F"}