@ekairos/dataset 1.22.39-beta.development.0 → 1.22.39

package/dist/notation.js

@@ -0,0 +1,424 @@
+/**
+ * Formal notation for datasets — the dataset stated intensionally.
+ *
+ * A dataset has TWO CO-EQUAL FACES at the same level:
+ * - its formal DEFINITION (this notation: the proposition that defines the
+ *   set, in LaTeX), and
+ * - its MATERIALIZATION (the rows + the code that produces them).
+ * The notation is not a comment about the data; it IS the dataset, written
+ * as a logical statement. The materialization is the same set written
+ * extensionally. Neither is subordinate to the other.
+ *
+ * The SAME notation plays two roles across the lifecycle: it is the PLAN
+ * (status "plan": stated first, the materialization is built to realize it)
+ * and, once finalized, the RESULT (status "result": it describes exactly
+ * what was produced). It is iterated in between — every revision keeps the
+ * prior version in `history`, so the discovery trail stays visible.
+ *
+ * The definition is a logical proposition, possibly DERIVED (a syllogism),
+ * so it is NOT, in general, mechanically verifiable: a predicate may be
+ * semantic ("x es una frase divertida") and the set is still well-formed.
+ * We TRUST the formality and the produced dataset — there is no verdict.
+ *
+ * SOME predicates happen to be arithmetic (a row count, a field type, a
+ * preserved total). For those, and only those, we attach OPTIONAL evidence
+ * computed over the rows. It is advisory: a contradiction is a hint, never
+ * a claim that the dataset is invalid. Predicates with no arithmetic form
+ * are "asserted" — trusted. Nothing here blocks or changes a build; the
+ * notation rides on dataset_datasets.notation.
+ */
+/**
+ * Iterate the notation: every revision bumps the version and appends to
+ * history, so the discovery trail (sets/variables found along the way)
+ * stays visible.
+ */
+export function reviseDatasetNotation(previous, input) {
+    const version = (previous?.version ?? 0) + 1;
+    const revision = {
+        version,
+        latex: input.latex,
+        reason: input.reason,
+        at: Date.now(),
+    };
+    return {
+        version,
+        status: input.final ? "result" : "plan",
+        latex: input.latex,
+        symbols: input.symbols ?? previous?.symbols ?? [],
+        predicates: input.predicates ?? previous?.predicates ?? [],
+        history: [...(previous?.history ?? []), revision],
+    };
+}
+/* ── LaTeX helpers ──────────────────────────────────────────────── */
+/** escape an identifier for use inside \text{} */
+export function latexIdentifier(name) {
+    return `\\text{${String(name).replace(/([#$%&_{}])/g, "\\$1")}}`;
+}
+function latexFieldType(type) {
+    if (type === "number")
+        return "\\mathbb{R}";
+    if (type === "integer")
+        return "\\mathbb{Z}";
+    if (type === "boolean")
+        return "\\{\\top,\\bot\\}";
+    return "\\Sigma^{*}";
+}
+const JSON_SCHEMA_KEYWORDS = new Set([
+    "type",
+    "title",
+    "description",
+    "required",
+    "items",
+    "additionalProperties",
+]);
+function schemaProperties(schema) {
+    const root = (schema?.schema ?? schema ?? {});
+    if (root.properties && typeof root.properties === "object") {
+        return root.properties;
+    }
+    // flat shape from query inference: { fieldName: "type", ... }
+    const flat = {};
+    for (const [key, value] of Object.entries(root)) {
+        if (JSON_SCHEMA_KEYWORDS.has(key))
+            continue;
+        if (typeof value === "string")
+            flat[key] = value;
+        else if (value && typeof value === "object" && typeof value.type === "string") {
+            flat[key] = value;
+        }
+    }
+    return flat;
+}
+/**
+ * A query-backed dataset has a complete deterministic description: the
+ * dataset is the image of a known query over a known domain. No model is
+ * involved, so here the formal definition and its predicates derive
+ * mechanically from the query, the inferred schema and the row count — and
+ * those predicates DO carry arithmetic evidence (the special case where the
+ * formal claims happen to be fully mechanical).
+ */
+export function inferQueryNotation(params) {
+    const sources = params.entityNames.length ? params.entityNames : ["Domain"];
+    const sourceSymbols = sources.map((name) => ({
+        name,
+        latex: latexIdentifier(name),
+        kind: "set",
+        description: `Entidad de origen ${name}`,
+    }));
+    const union = sources.map((name) => latexIdentifier(name)).join(" \\cup ");
+    const latex = `\\mathcal{D} = \\left\\{\\, r \\;\\middle|\\; r \\in Q\\!\\left(${union}\\right) \\right\\}`;
+    const properties = schemaProperties(params.schema);
+    const predicates = [
+        {
+            id: "cardinality",
+            description: `El dataset tiene exactamente ${params.rowCount} filas`,
+            latex: `|\\mathcal{D}| = ${params.rowCount}`,
+            check: { kind: "row_count", op: "=", value: params.rowCount },
+        },
+    ];
+    for (const [field, raw] of Object.entries(properties)) {
+        const type = typeof raw === "string" ? raw : String(raw?.type ?? "");
+        if (!["number", "integer", "boolean", "string"].includes(type))
+            continue;
+        predicates.push({
+            id: `type_${field}`,
+            description: `Toda fila tiene ${field} de tipo ${type} (o nulo)`,
+            latex: `\\forall r \\in \\mathcal{D}:\\; r.${latexIdentifier(field)} \\in ${latexFieldType(type)} \\cup \\{\\varnothing\\}`,
+            check: {
+                kind: "field_type",
+                field,
+                type: type,
+                allowNull: true,
+            },
+        });
+    }
+    return reviseDatasetNotation(null, {
+        latex,
+        symbols: [
+            {
+                name: "D",
+                latex: "\\mathcal{D}",
+                kind: "set",
+                description: params.explanation?.trim() || "Dataset materializado",
+            },
+            {
+                name: "Q",
+                kind: "function",
+                description: "Consulta InstaQL aplicada al dominio",
+            },
+            ...sourceSymbols,
+        ],
+        predicates,
+        reason: "Notación determinística derivada de la consulta al dominio",
+        final: true,
+    });
+}
+/* ── arithmetic evaluation ──────────────────────────────────────── */
+function readPath(row, path) {
+    let current = row;
+    for (const segment of String(path).split(".")) {
+        if (current === null || current === undefined)
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+function compare(op, left, right, tolerance = 0) {
+    switch (op) {
+        case "=":
+            return Math.abs(left - right) <= tolerance;
+        case "!=":
+            return Math.abs(left - right) > tolerance;
+        case "<":
+            return left < right;
+        case "<=":
+            return left <= right + tolerance;
+        case ">":
+            return left > right;
+        case ">=":
+            return left >= right - tolerance;
+    }
+}
+export function evaluateNotationCheck(rows, check) {
+    switch (check.kind) {
+        case "row_count": {
+            const ok = compare(check.op, rows.length, check.value);
+            return { ok, detail: `|D| = ${rows.length} ${check.op} ${check.value}` };
+        }
+        case "field_type": {
+            let failures = 0;
+            let firstFailure = "";
+            for (const row of rows) {
+                const value = readPath(row, check.field);
+                if (value === null || value === undefined) {
+                    if (check.allowNull)
+                        continue;
+                    failures += 1;
+                    if (!firstFailure)
+                        firstFailure = "null";
+                    continue;
+                }
+                const okValue = check.type === "number"
+                    ? typeof value === "number" && Number.isFinite(value)
+                    : check.type === "integer"
+                        ? typeof value === "number" && Number.isInteger(value)
+                        : check.type === "boolean"
+                            ? typeof value === "boolean"
+                            : typeof value === "string";
+                if (!okValue) {
+                    failures += 1;
+                    if (!firstFailure)
+                        firstFailure = JSON.stringify(value)?.slice(0, 40) ?? "?";
+                }
+            }
+            return {
+                ok: failures === 0,
+                detail: failures === 0
+                    ? `∀r: ${check.field} : ${check.type}`
+                    : `${failures}/${rows.length} filas violan ${check.field} : ${check.type} (ej: ${firstFailure})`,
+            };
+        }
+        case "field_range": {
+            let failures = 0;
+            for (const row of rows) {
+                const value = readPath(row, check.field);
+                if (typeof value !== "number" || Number.isNaN(value))
+                    continue;
+                if (check.min !== undefined && value < check.min)
+                    failures += 1;
+                else if (check.max !== undefined && value > check.max)
+                    failures += 1;
+            }
+            const bounds = [
+                check.min !== undefined ? `≥ ${check.min}` : "",
+                check.max !== undefined ? `≤ ${check.max}` : "",
+            ]
+                .filter(Boolean)
+                .join(" ∧ ");
+            return {
+                ok: failures === 0,
+                detail: failures === 0
+                    ? `∀r: ${check.field} ${bounds}`
+                    : `${failures}/${rows.length} filas fuera de rango en ${check.field}`,
+            };
+        }
+        case "field_in": {
+            const allowed = new Set(check.values.map((value) => JSON.stringify(value)));
+            let failures = 0;
+            for (const row of rows) {
+                const value = readPath(row, check.field);
+                if (value === null || value === undefined)
+                    continue;
+                if (!allowed.has(JSON.stringify(value)))
+                    failures += 1;
+            }
+            return {
+                ok: failures === 0,
+                detail: failures === 0
+                    ? `∀r: ${check.field} ∈ {${check.values.join(", ")}}`
+                    : `${failures}/${rows.length} filas con ${check.field} fuera del conjunto`,
+            };
+        }
+        case "field_nonnull": {
+            let failures = 0;
+            for (const row of rows) {
+                const value = readPath(row, check.field);
+                if (value === null || value === undefined || value === "")
+                    failures += 1;
+            }
+            return {
+                ok: failures === 0,
+                detail: failures === 0
+                    ? `∀r: ${check.field} ≠ ∅`
+                    : `${failures}/${rows.length} filas con ${check.field} vacío`,
+            };
+        }
+        case "field_matches": {
+            let regex;
+            try {
+                regex = new RegExp(check.pattern);
+            }
+            catch {
+                return { ok: false, detail: `patrón inválido: ${check.pattern}` };
+            }
+            let failures = 0;
+            for (const row of rows) {
+                const value = readPath(row, check.field);
+                if (typeof value !== "string")
+                    continue;
+                if (!regex.test(value))
+                    failures += 1;
+            }
+            return {
+                ok: failures === 0,
+                detail: failures === 0
+                    ? `∀r: ${check.field} ~ /${check.pattern}/`
+                    : `${failures}/${rows.length} filas no matchean /${check.pattern}/`,
+            };
+        }
+        case "unique": {
+            const seen = new Set();
+            let duplicates = 0;
+            for (const row of rows) {
+                const key = JSON.stringify(check.fields.map((field) => readPath(row, field)));
+                if (seen.has(key))
+                    duplicates += 1;
+                else
+                    seen.add(key);
+            }
+            return {
+                ok: duplicates === 0,
+                detail: duplicates === 0
+                    ? `(${check.fields.join(", ")}) es clave`
+                    : `${duplicates} duplicados sobre (${check.fields.join(", ")})`,
+            };
+        }
+        case "aggregate": {
+            const values = [];
+            for (const row of rows) {
+                if (check.fn === "count" && !check.field)
+                    continue;
+                const value = readPath(row, String(check.field));
+                if (typeof value === "number" && Number.isFinite(value))
+                    values.push(value);
+            }
+            let actual;
+            switch (check.fn) {
+                case "count":
+                    actual = check.field ? values.length : rows.length;
+                    break;
+                case "sum":
+                    actual = values.reduce((total, value) => total + value, 0);
+                    break;
+                case "min":
+                    actual = values.length ? Math.min(...values) : Number.NaN;
+                    break;
+                case "max":
+                    actual = values.length ? Math.max(...values) : Number.NaN;
+                    break;
+                case "avg":
+                    actual = values.length
+                        ? values.reduce((total, value) => total + value, 0) / values.length
+                        : Number.NaN;
+                    break;
+            }
+            const tolerance = check.tolerance ?? 1e-9;
+            const ok = Number.isFinite(actual) && compare(check.op, actual, check.value, tolerance);
+            return {
+                ok,
+                detail: `${check.fn}(${check.field ?? "*"}) = ${Number.isFinite(actual) ? actual : "∅"} ${check.op} ${check.value}`,
+            };
+        }
+        case "and": {
+            const results = check.checks.map((inner) => evaluateNotationCheck(rows, inner));
+            return {
+                ok: results.every((result) => result.ok),
+                detail: results.map((result) => result.detail).join(" ∧ "),
+            };
+        }
+        case "or": {
+            const results = check.checks.map((inner) => evaluateNotationCheck(rows, inner));
+            return {
+                ok: results.some((result) => result.ok),
+                detail: results.map((result) => result.detail).join(" ∨ "),
+            };
+        }
+        case "not": {
+            const result = evaluateNotationCheck(rows, check.check);
+            return { ok: !result.ok, detail: `¬(${result.detail})` };
+        }
+        case "implies": {
+            const antecedent = evaluateNotationCheck(rows, check.if);
+            if (!antecedent.ok) {
+                return { ok: true, detail: `(${antecedent.detail}) → ⊤ (antecedente falso)` };
+            }
+            const consequent = evaluateNotationCheck(rows, check.then);
+            return {
+                ok: consequent.ok,
+                detail: `(${antecedent.detail}) → (${consequent.detail})`,
+            };
+        }
+    }
+}
+/**
+ * Annotate a notation with ADVISORY arithmetic evidence over the produced
+ * rows. Never throws, never blocks, and never changes the notation's
+ * lifecycle status — the dataset's validity is trusted, not proven here.
+ *
+ * Each predicate is reported as:
+ * - "asserted"     no arithmetic form (formal/semantic claim, trusted)
+ * - "supported"    arithmetic evidence agrees
+ * - "contradicted" arithmetic evidence disagrees (a hint to look, not a
+ *                  verdict that the dataset is wrong)
+ * A check that can't be evaluated stays "asserted" — we don't downgrade a
+ * trusted claim because of a malformed mechanical form.
+ */
+export function annotateNotationEvidence(notation, rows) {
+    const checks = [];
+    for (const predicate of notation.predicates ?? []) {
+        if (!predicate.check) {
+            checks.push({ predicateId: predicate.id, status: "asserted" });
+            continue;
+        }
+        try {
+            const outcome = evaluateNotationCheck(rows, predicate.check);
+            checks.push({
+                predicateId: predicate.id,
+                status: outcome.ok ? "supported" : "contradicted",
+                detail: outcome.detail,
+            });
+        }
+        catch (error) {
+            checks.push({
+                predicateId: predicate.id,
+                status: "asserted",
+                detail: `no evaluable: ${String(error).slice(0, 120)}`,
+            });
+        }
+    }
+    return {
+        ...notation,
+        checks,
+        evidenceAt: Date.now(),
+    };
+}

package/dist/query/index.d.ts

@@ -1,2 +1 @@
-export * from "./queryDomain";
-//# sourceMappingURL=index.d.ts.map
+export * from "./queryDomain.js";

package/dist/query/index.js

@@ -1,18 +1 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./queryDomain"), exports);
-//# sourceMappingURL=index.js.map
+export * from "./queryDomain.js";

package/dist/query/queryDomain.d.ts

@@ -1,9 +1,8 @@
-import type { QueryDomainStepInput, QueryDomainStepResult } from "./queryDomain.step";
-export type QueryDomainInput = QueryDomainStepInput;
+import { type QueryDomainStepInput, type QueryDomainStepResult } from "./queryDomain.step.js";
+export type QueryDomainInput = Omit<QueryDomainStepInput, "runtime">;
 export type QueryDomainResult = QueryDomainStepResult;
 /**
  * Workflow-compatible domain query.
  * Always returns a dataset + preview rows.
  */
-export declare function queryDomain(input: QueryDomainInput): Promise<QueryDomainResult>;
-//# sourceMappingURL=queryDomain.d.ts.map
+export declare function queryDomain(runtime: any, input: QueryDomainInput): Promise<QueryDomainResult>;

package/dist/query/queryDomain.js

@@ -1,46 +1,9 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.queryDomain = queryDomain;
+import { queryDomainStep } from "./queryDomain.step.js";
 /**
  * Workflow-compatible domain query.
  * Always returns a dataset + preview rows.
  */
-async function queryDomain(input) {
+export async function queryDomain(runtime, input) {
     "use step";
-    const { queryDomainStep } = await Promise.resolve().then(() => __importStar(require("./queryDomain.step")));
-    return await queryDomainStep(input);
+    return await queryDomainStep({ runtime, ...input });
 }
-//# sourceMappingURL=queryDomain.js.map

package/dist/query/queryDomain.step.d.ts

@@ -1,4 +1,5 @@
 export type QueryDomainStepInput = {
+    runtime: any;
     query: Record<string, any>;
     explanation: string;
     title?: string;
@@ -11,4 +12,3 @@ export type QueryDomainStepResult = {
     explanation: string;
 };
 export declare function queryDomainStep(params: QueryDomainStepInput): Promise<QueryDomainStepResult>;
-//# sourceMappingURL=queryDomain.step.d.ts.map

package/dist/query/queryDomain.step.js

@@ -1,9 +1,6 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.queryDomainStep = queryDomainStep;
-const admin_1 = require("@instantdb/admin");
-const runtime_1 = require("@ekairos/events/runtime");
-const service_1 = require("../service");
+import { DatasetService } from "../service.js";
+import { createDatasetId } from "../id.js";
+import { annotateNotationEvidence, inferQueryNotation } from "../notation.js";
 function normalizeRows(result) {
     if (!result || typeof result !== "object")
         return [];
@@ -49,17 +46,31 @@ function inferSchema(rows) {
     }
     return { schema };
 }
-async function queryDomainStep(params) {
-    "use step";
-    const env = await (0, runtime_1.getContextEnv)();
-    const runtime = await (0, runtime_1.getContextRuntime)(env);
+async function getRuntimeDb(runtime) {
+    if (!runtime) {
+        throw new Error("Dataset query step requires runtime.");
+    }
     const db = runtime.db;
-    const service = new service_1.DatasetService(db);
-    const datasetId = params.datasetId ?? (0, admin_1.id)();
+    return typeof db === "function" ? await db.call(runtime) : db;
+}
+export async function queryDomainStep(params) {
+    "use step";
+    const db = await getRuntimeDb(params.runtime);
+    const service = new DatasetService(db);
+    const datasetId = params.datasetId ?? createDatasetId();
     const queryResult = await db.query(params.query);
     const rows = normalizeRows(queryResult);
     const previewRows = rows.slice(0, 20);
     const schema = inferSchema(rows);
+    // query-backed datasets carry a fully deterministic formal notation:
+    // the set definition, its symbols and its predicates derive mechanically
+    // from the query + rows, so their arithmetic evidence is immediate
+    const notation = annotateNotationEvidence(inferQueryNotation({
+        entityNames: Object.keys(params.query ?? {}),
+        rowCount: rows.length,
+        schema,
+        explanation: params.explanation,
+    }), rows);
     const createRes = await service.createDataset({
         id: datasetId,
         title: params.title ?? "domain.query",
@@ -67,6 +78,7 @@ async function queryDomainStep(params) {
         instructions: params.explanation,
         analysis: { explanation: params.explanation, query: params.query },
         schema,
+        notation,
         createdAt: Date.now(),
         updatedAt: Date.now(),
     });
@@ -101,4 +113,3 @@ async function queryDomainStep(params) {
         explanation: params.explanation,
     };
 }
-//# sourceMappingURL=queryDomain.step.js.map

package/dist/sandbox/steps.d.ts

@@ -1,13 +1,7 @@
+import { type SandboxConfig } from "@ekairos/sandbox";
 export type DatasetSandboxId = string;
-export type CreateDatasetSandboxParams = {
-    runtime?: string;
-    timeoutMs?: number;
-    ports?: number[];
-    resources?: {
-        vcpus?: number;
-    };
-    purpose?: string;
-    params?: Record<string, any>;
+export type CreateDatasetSandboxParams = Pick<SandboxConfig, "provider" | "timeoutMs" | "ports" | "resources" | "purpose" | "params" | "env" | "domain" | "dataset" | "vercel"> & {
+    sandboxRuntime?: string;
 };
 export type DatasetSandboxRunCommandResult = {
     exitCode: number;
@@ -15,33 +9,47 @@ export type DatasetSandboxRunCommandResult = {
     stderr: string;
 };
 export declare function createDatasetSandboxStep(params: {
-    env: any;
+    runtime: any;
 } & CreateDatasetSandboxParams): Promise<{
     sandboxId: DatasetSandboxId;
 }>;
 export declare function runDatasetSandboxCommandStep(params: {
-    env: any;
+    runtime: any;
     sandboxId: DatasetSandboxId;
     cmd: string;
     args?: string[];
 }): Promise<DatasetSandboxRunCommandResult>;
 export declare function writeDatasetSandboxFilesStep(params: {
-    env: any;
+    runtime: any;
     sandboxId: DatasetSandboxId;
     files: Array<{
         path: string;
         contentBase64: string;
     }>;
 }): Promise<void>;
+export declare function writeDatasetSandboxTextFilesStep(params: {
+    runtime: any;
+    sandboxId: DatasetSandboxId;
+    files: Array<{
+        path: string;
+        content: string;
+    }>;
+}): Promise<void>;
 export declare function readDatasetSandboxFileStep(params: {
-    env: any;
+    runtime: any;
     sandboxId: DatasetSandboxId;
     path: string;
 }): Promise<{
     contentBase64: string;
 }>;
+export declare function readDatasetSandboxTextFileStep(params: {
+    runtime: any;
+    sandboxId: DatasetSandboxId;
+    path: string;
+}): Promise<{
+    content: string;
+}>;
 export declare function stopDatasetSandboxStep(params: {
-    env: any;
+    runtime: any;
     sandboxId: DatasetSandboxId;
 }): Promise<void>;
-//# sourceMappingURL=steps.d.ts.map