@telorun/sqlite 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+# SUSTAINABLE USE LICENSE (Fair-code)
+
+Copyright (c) 2026 CodeNet Sp. z o.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, and distribute the Software for any purpose—including commercial purposes—subject to the following conditions:
+
+1. ANTI-COMPETITION RESTRICTION: The Software may not be provided to third parties as a managed service, commercial SaaS (Software-as-a-Service), PaaS (Platform-as-a-Service), BaaS (Backend-as-a-Service), or similar offering where the primary value provided to the user is the functionality of the Software itself, without a separate commercial license from the copyright holder.
+
+2. PERMITTED COMMERCIAL USE: You are free to use the Software to build, host, and monetize your own commercial applications, products, and services, provided such use does not violate Clause 1.
+
+3. ATTRIBUTION: This copyright notice and license must be included in all copies or substantial portions of the Software.
+
+4. CONTRIBUTIONS: Contributions to the Software are welcome and encouraged. By contributing, you agree that your contributions may be incorporated into the Software and distributed under this license.
+
+5. DISCLAIMER: The Software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the Software or the use or other dealings in the Software.
+
+For commercial licensing, managed hosting exemptions, or enterprise inquiries, please contact <contact@codenet.pl>.

package/README.md

@@ -0,0 +1,94 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/telorun/telo/main/assets/telo.png" alt="Telo" width="200" />
+</p>
+
+<h1 align="center">Telo</h1>
+
+<p align="center">Runtime for declarative backends.</p>
+
+<p align="center">
+  <a href="https://github.com/telorun/telo/actions/workflows/test.yml"><img alt="Tests" src="https://github.com/telorun/telo/actions/workflows/test.yml/badge.svg" /></a>
+  <a href="https://www.npmjs.com/package/@telorun/cli"><img alt="node" src="https://img.shields.io/node/v/@telorun/cli" /></a>
+  <br />
+  <a href="https://github.com/telorun/telo/commits/main"><img alt="Last commit" src="https://img.shields.io/github/last-commit/telorun/telo" /></a>
+  <a href="https://github.com/telorun/telo/issues"><img alt="Issues" src="https://img.shields.io/github/issues/telorun/telo" /></a>
+  <a href="https://github.com/telorun/telo/pulls"><img alt="Pull requests" src="https://img.shields.io/github/issues-pr/telorun/telo" /></a>
+  <br />
+  <img alt="Changesets" src="https://img.shields.io/badge/maintained%20with-changesets-176de3" />
+</p>
+
+Telo is an execution engine (Micro-Kernel) that runs logic defined entirely in YAML manifests. Instead of writing imperative backend code, you define your routes, databases, schemas, and AI workflows as atomic, interconnected YAML documents. Telo takes those manifests and runs them.
+
+Built to be language-agnostic and infinitely extensible.
+
+```bash
+# Reconcile your manifest into a running backend
+$ telo ./examples/todo-app
+
+{"level":30,"time":1771610393008,"pid":1310178,"hostname":"dev","msg":"Server listening at http://127.0.0.1:8077"}
+```
+
+## Why use Telo?
+
+- **Open Standards:** Built on YAML, JSON Schema, and CEL — no proprietary DSL.
+- **Static Analysis:** CEL type checking, reference validation, and IDE diagnostics catch errors before runtime.
+- **Micro-Kernel Architecture:** Telo itself knows nothing about HTTP or SQL. Everything is a module you import, scope, and compose with typed variable and secret contracts.
+- **Language Agnostic:** Available as a Node.js runtime today, with a shared YAML runtime contract that allows for future Rust or Go implementations without changing your manifests.
+
+## What It Does
+
+- **Loads** YAML resources and compiles CEL expressions (`${{ }}`) into an in-memory registry.
+- **Resolves** resource dependencies via a multi-pass init loop, handling ordering automatically.
+- **Indexes** resources by Kind and Name for constant-time lookup.
+- **Dispatches** execution to the controller that owns each Kind.
+
+## Example manifest
+
+See [examples/](./examples/) for a list of working applications.
+
+## Status
+
+Telo is under heavy development. While it is pre-1.0, breaking changes ship in **minor** releases — manifest shapes, kind schemas, and APIs can change between versions. Pin your imports and expect to update manifests when you upgrade. The core runtime, module system, and standard library are functional, but Telo is not yet recommended for production use.
+
+**1.0 lands when the Rust kernel reaches feature parity with the Node.js implementation** — that is the milestone that freezes the manifest contract across runtimes.
+
+## The Meaning of Telo
+
+The name Telo is derived from the Greek root Telos - meaning the "end goal", "purpose", or "final state". That is exactly the philosophy behind this runtime. In standard imperative programming, you have to write thousands of lines of code to tell a server exactly how to start. With Telo, you simply declare your desired final state.
+
+You define the end state. Telo makes it real.
+
+## Philosophy
+
+Modern platforms often spend disproportionate effort on technical mechanics-wiring frameworks, managing infrastructure, and negotiating toolchains-while the original business problem gets delayed or diluted. Telo pushes in the opposite direction: it treats kernel execution as a stable, predictable host so teams can concentrate on the **business logic and outcomes** instead of the plumbing.
+
+By separating "what the system should do" from "how it is hosted", the runtime reduces friction for domain‑level changes. Teams can move faster on product requirements, experiment more safely, and keep conversations centered on value delivered rather than implementation trivia.
+
+Telo also aims to **join forces across all programming language communities**, so the best ideas, patterns, and implementations can converge into a shared kernel truth without forcing everyone into a single stack.
+
+YAML also makes the system more **AI‑friendly** than traditional programming languages: it is explicit, structured, and easier for tools to generate, review, and transform without losing intent.
+
+## Modularity
+
+Telo is built around **modules** that own specific resource kinds. A module is loaded from a manifest, declares which kinds it implements, and then receives only the resources of those kinds. This keeps concerns isolated and lets teams compose systems from focused building blocks rather than monolithic services.
+
+At kernel execution time, execution is always routed by **Kind.Name**. The kernel resolves the Kind to its owning module and hands off execution. Modules can call back into the kernel to execute other resources, enabling composition without tight coupling.
+
+## Architecture
+
+The architecture is inspired by Kubernetes-style manifests: declarative resources, explicit kinds, and a control plane that routes work based on those definitions.
+Those manifests were taken to the next level by allowing them to run inside a standalone runtime host.
+
+## See more at
+
+- [Telo Kernel](./kernel/README.md)
+- [Telo SDK for module authors](sdk/README.md)
+- [Modules](modules/README.md)
+
+## License
+
+See [LICENSE](https://github.com/telorun/telo/blob/main/LICENSE).
+
+## Contribution Note
+
+By contributing, you agree that code and examples in this repository may be translated or re‑implemented in other programming languages (including by AI systems) to support the project’s polyglot goals.

package/dist/connection-controller.d.ts

@@ -0,0 +1,22 @@
+import type { ResourceContext } from "@telorun/sdk";
+import { SqlConnectionBase } from "@telorun/sql";
+import { Kysely } from "kysely";
+import type { SqliteDb } from "./sqlite-driver-interface.js";
+interface SqliteConnectionManifest {
+    metadata: {
+        name: string;
+        module: string;
+    };
+    /** File path, or omitted / `:memory:` for an in-memory database. */
+    file?: string;
+}
+declare class SqliteConnection extends SqlConnectionBase {
+    private readonly sqlite;
+    constructor(db: Kysely<any>, sqlite: SqliteDb, ctx: ResourceContext);
+    /** The driver's native multi-statement entry point — kysely binds one
+     *  statement per call. */
+    executeScript(sql: string): Promise<void>;
+}
+export declare function register(): void;
+export declare function create(resource: SqliteConnectionManifest, ctx: ResourceContext): Promise<SqliteConnection>;
+export {};

package/dist/connection-controller.js

@@ -0,0 +1,67 @@
+import { quoteAnsiIdentifier, SqlConnectionBase } from "@telorun/sql";
+import { Kysely, SqliteAdapter, SqliteDialect } from "kysely";
+const sqliteDialect = {
+    placeholderStyle: "qmark",
+    quoteIdentifier: quoteAnsiIdentifier,
+    // SQLite has no array type, so set membership expands to one placeholder per
+    // element.
+    renderIn(column, values, addParam) {
+        return `${column} IN (${values.map((value) => addParam(value)).join(", ")})`;
+    },
+};
+class SqliteConnection extends SqlConnectionBase {
+    sqlite;
+    constructor(db, sqlite, ctx) {
+        super(db, sqliteDialect, ctx);
+        this.sqlite = sqlite;
+    }
+    /** The driver's native multi-statement entry point — kysely binds one
+     *  statement per call. */
+    async executeScript(sql) {
+        this.sqlite.exec(sql);
+    }
+}
+// Kysely's stock SQLite adapter reports `supportsTransactionalDdl = false`, so
+// its Migrator runs migrations without a transaction. SQLite does support
+// transactional DDL, so we flip the flag — letting the Migrator wrap the whole
+// migration batch in a single transaction, matching PostgreSQL.
+class TransactionalSqliteAdapter extends SqliteAdapter {
+    get supportsTransactionalDdl() {
+        return true;
+    }
+}
+class TransactionalSqliteDialect extends SqliteDialect {
+    createAdapter() {
+        return new TransactionalSqliteAdapter();
+    }
+}
+async function openSqliteDatabase(file = ":memory:") {
+    // Auto-create the parent directory for file-backed databases. SQLite
+    // drivers fail-fast when the directory doesn't exist; mirroring `mkdir
+    // -p` here lets manifests use paths like `./tmp/foo.sqlite` without a
+    // separate filesystem-prep step. `:memory:` skips filesystem entirely.
+    if (file !== ":memory:") {
+        const { mkdir } = await import("node:fs/promises");
+        const { dirname } = await import("node:path");
+        const dir = dirname(file);
+        if (dir && dir !== "." && dir !== "/") {
+            await mkdir(dir, { recursive: true });
+        }
+    }
+    // Route through this package's own `./sqlite-driver` subpath export so the
+    // resolver selects the driver per runtime (Bun → bun:sqlite, Node →
+    // better-sqlite3). A manual `typeof Bun` check with relative imports gets
+    // flattened by the controller bundler into an unconditional top-level
+    // `import "bun:sqlite"`, which Node's ESM loader rejects before the guard
+    // runs; an external `@telorun/*` specifier stays a deferred dynamic import.
+    const { openDatabase } = await import("@telorun/sqlite/sqlite-driver");
+    return openDatabase(file);
+}
+export function register() { }
+export async function create(resource, ctx) {
+    const sqlite = await openSqliteDatabase(resource.file ?? ":memory:");
+    const db = new Kysely({
+        dialect: new TransactionalSqliteDialect({ database: sqlite }),
+    });
+    return new SqliteConnection(db, sqlite, ctx);
+}

package/dist/schema/schema-controller.d.ts

@@ -0,0 +1,37 @@
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { type MigrationMap, type ReclaimPolicy, type SqlConnection } from "@telorun/sql";
+import type { SqliteTableResource } from "./table-controller.js";
+interface SqliteSchemaManifest {
+    metadata: {
+        name: string;
+        module: string;
+    };
+    connection: SqlConnection;
+    version?: string;
+    ledger?: string;
+    tables?: SqliteTableResource[];
+    beforeMigrations?: MigrationMap;
+    migrations?: MigrationMap;
+    reclaim?: ReclaimPolicy;
+}
+/**
+ * `SQLite.Schema` — the single schema-change kind: declared tables and
+ * imperative migrations reconciled in one boot pass, under one clock.
+ *
+ * SQLite has exactly one namespace, so unlike the PostgreSQL kind there is no
+ * `schema:` field to name and nothing to create.
+ */
+declare class SqliteSchemaResource implements ResourceInstance {
+    private readonly manifest;
+    private readonly ctx;
+    constructor(manifest: SqliteSchemaManifest, ctx: ResourceContext);
+    /** Configured state is pulled, observed state is pushed — everything this
+     *  resource knows is learned while running, so the snapshot is empty and the
+     *  whole report arrives through `setStatus`. It still has to exist: a
+     *  resource that publishes nothing is absent from the `resources` scope. */
+    snapshot(): Record<string, unknown>;
+    run(): Promise<void>;
+}
+export declare function register(): void;
+export declare function create(resource: SqliteSchemaManifest, ctx: ResourceContext): Promise<SqliteSchemaResource>;
+export {};

package/dist/schema/schema-controller.js

@@ -0,0 +1,49 @@
+import { resolveSqlConnection, runSchemaPass, } from "@telorun/sql";
+import { SqliteSchemaDriver } from "./sqlite-schema-driver.js";
+/**
+ * `SQLite.Schema` — the single schema-change kind: declared tables and
+ * imperative migrations reconciled in one boot pass, under one clock.
+ *
+ * SQLite has exactly one namespace, so unlike the PostgreSQL kind there is no
+ * `schema:` field to name and nothing to create.
+ */
+class SqliteSchemaResource {
+    manifest;
+    ctx;
+    constructor(manifest, ctx) {
+        this.manifest = manifest;
+        this.ctx = ctx;
+    }
+    /** Configured state is pulled, observed state is pushed — everything this
+     *  resource knows is learned while running, so the snapshot is empty and the
+     *  whole report arrives through `setStatus`. It still has to exist: a
+     *  resource that publishes nothing is absent from the `resources` scope. */
+    snapshot() {
+        return {};
+    }
+    async run() {
+        const connection = resolveSqlConnection(this.manifest.connection, this.ctx, () => `SQLite.Schema "${this.manifest.metadata.name}": 'connection'`);
+        if (!connection) {
+            throw new Error(`SQLite.Schema "${this.manifest.metadata.name}": missing connection`);
+        }
+        const status = await runSchemaPass(new SqliteSchemaDriver(connection), this.ctx, {
+            schema: "main",
+            ledger: this.manifest.ledger,
+            version: this.manifest.version,
+            tables: (this.manifest.tables ?? []).map((table) => table.declaration),
+            beforeMigrations: this.manifest.beforeMigrations ?? {},
+            migrations: this.manifest.migrations ?? {},
+            reclaim: this.manifest.reclaim,
+        });
+        for (const key of status.orphanedMigrations) {
+            // Deleting decade-old migrations from a manifest is normal, so an applied
+            // key with no declaration is reported and never an error.
+            this.ctx.log.info("Applied migration has no declaration", { "sql.migration.name": key });
+        }
+        this.ctx.setStatus({ ...status });
+    }
+}
+export function register() { }
+export async function create(resource, ctx) {
+    return new SqliteSchemaResource(resource, ctx);
+}

package/dist/schema/sqlite-schema-driver.d.ts

@@ -0,0 +1,70 @@
+import { type ChangeSafety, type DeclaredColumn, type DeclaredForeignKey, type DeclaredIndex, type DeclaredTable, type LiveColumn, type SchemaObjectId, type LiveTable, type LedgerTables, type LiveForeignKey, type SchemaDriver, type SqlConnection } from "@telorun/sql";
+/**
+ * SQLite's half of declarative schema.
+ *
+ * The vocabulary is honestly smaller than PostgreSQL's because the engine is:
+ * five storage classes, no namespaces, no `ALTER COLUMN`, and foreign keys that
+ * exist only as part of the table they were created with. Nothing here pretends
+ * otherwise — a change SQLite cannot make in place is refused with the reason,
+ * which is what sends the author to a `migrations:` entry that rebuilds the
+ * table rather than leaving them with a silently unapplied declaration.
+ */
+/** SQLite storage classes. There is no date, boolean or UUID type — those are
+ *  conventions over these five, and inventing names for them here would be the
+ *  lowest-common-denominator type vocabulary this design rejects. */
+export declare const SQLITE_TYPES: readonly ["integer", "real", "text", "blob", "numeric"];
+export type SqliteType = (typeof SQLITE_TYPES)[number];
+export declare class SqliteSchemaDriver implements SchemaDriver {
+    #private;
+    readonly connection: SqlConnection;
+    constructor(connection: SqlConnection);
+    quote(name: string): string;
+    /** SQLite has exactly one namespace, so a table is named on its own. */
+    qualify(_schema: string, table: string): string;
+    /**
+     * SQLite has no advisory lock, so the contract is met by a weaker mechanism
+     * and this says which.
+     *
+     * The engine serializes WRITERS, so no two passes interleave a write; each
+     * group `runAtomically` submits is a transaction. What is NOT excluded is two
+     * passes running concurrently against one database file and interleaving
+     * between groups. That is survivable rather than merely unlikely: every step
+     * is derived from live state and re-derivable, the DDL is `IF NOT EXISTS`, and
+     * the ledger writes are last in their groups — so two racing passes converge
+     * on the same schema instead of diverging.
+     *
+     * What it does not buy is exclusion for the destructive phase: two passes
+     * could both find a tombstone eligible, and the second's `DROP … IF EXISTS`
+     * is then a no-op. Acceptable because the outcome is identical; a genuine
+     * lock would need `BEGIN IMMEDIATE` held across the whole pass, which cannot
+     * nest with the per-group transactions.
+     */
+    withLock<T>(_schema: string, body: () => Promise<T>): Promise<T>;
+    ensureNamespaceStatements(): string[];
+    ledgerStatements(_schema: string, tables: LedgerTables): string[];
+    now(): Promise<string>;
+    runAtomically(statements: readonly string[]): Promise<void>;
+    introspect(_schema: string, tables: readonly string[]): Promise<LiveTable[]>;
+    typeSignature(column: DeclaredColumn): string;
+    /** An index is dropped and recreated, which SQLite does support. */
+    classifyIndexChange(): ChangeSafety;
+    /** A foreign key exists only as part of the table it was created with, so
+     *  changing one means rebuilding the table. */
+    classifyForeignKeyChange(live: LiveForeignKey): ChangeSafety;
+    classifyAlter(live: LiveColumn, declared: DeclaredColumn): ChangeSafety;
+    classifyCopy(live: LiveColumn, target: DeclaredColumn): ChangeSafety;
+    createTable(schema: string, table: DeclaredTable): string[];
+    addColumn(schema: string, table: string, column: DeclaredColumn): string[];
+    /** Unreachable: `classifyAlter` refuses every in-place column change SQLite
+     *  cannot make, which is all of them. */
+    alterColumn(_schema: string, table: string, _live: LiveColumn, column: DeclaredColumn): string[];
+    copyColumn(schema: string, table: string, from: string, to: string): string[];
+    createIndex(schema: string, table: string, index: DeclaredIndex): string[];
+    dropIndex(_schema: string, _table: string, index: string): string[];
+    addForeignKey(_schema: string, table: string, fk: DeclaredForeignKey): string[];
+    /** Unreachable: `canReclaim` refuses a foreign key before the drop is planned. */
+    dropForeignKey(_schema: string, table: string, name: string): string[];
+    canReclaim(id: SchemaObjectId): ChangeSafety;
+    dropColumn(schema: string, table: string, column: string): string[];
+    dropTable(schema: string, table: string): string[];
+}