inistate-core 0.1.0

package/LICENSE

@@ -0,0 +1,82 @@
+INISTATE CORE — FREE-USE END USER LICENSE AGREEMENT
+Version 1.0
+
+Copyright (c) GNEY SOFTWARE PTE LTD. All rights reserved.
+
+This End User License Agreement ("Agreement") is a legal agreement between you
+(an individual or a single entity, "You") and GNEY SOFTWARE PTE LTD ("Licensor")
+for the inistate-core software, including the compiled binaries, bundled data
+files, and accompanying documentation (collectively, the "Software").
+
+inistate-core is FREE TO USE but is NOT open-source software. It is distributed
+as a closed, compiled artifact. The Software's source code is not provided, and
+this Agreement grants no rights to its source code.
+
+1. GRANT OF LICENSE
+   Subject to Your compliance with this Agreement, Licensor grants You a
+   worldwide, royalty-free, non-exclusive, non-transferable license to install
+   and run the Software, in unlimited quantity and for an unlimited period,
+   for any purpose, including production and commercial use, on infrastructure
+   You operate or control. You may run the Software forever at no charge.
+
+2. RESTRICTIONS
+   You may NOT:
+   (a) reverse engineer, decompile, or disassemble the Software, or otherwise
+       attempt to derive its source code, except to the extent this restriction
+       is expressly prohibited by applicable law;
+   (b) modify, adapt, or create derivative works of the Software's engine;
+   (c) redistribute, sublicense, sell, rent, lease, or host the Software as a
+       service to third parties, except for unmodified redistribution of the
+       official published package for installation by end users under this
+       Agreement;
+   (d) remove or alter any proprietary notices, labels, or this Agreement;
+   (e) use the Software to build a product that competes with the Inistate
+       Platform.
+
+3. OPEN COMPONENTS
+   The Software embeds and is designed to interoperate with separately published
+   open-source components — the Inistate schema and the Inistate MCP server —
+   which are licensed under the MIT License in their own repositories. Nothing
+   in this Agreement restricts Your rights under those licenses with respect to
+   those components. This Agreement governs only the closed inistate-core engine
+   and the compiled artifact as a whole.
+
+4. NO PATENT LICENSE
+   No license, immunity, or other right is granted to You under any patent,
+   patent application, or other intellectual property of Licensor or its
+   affiliates, whether by implication, estoppel, or otherwise, except for the
+   limited right to run the Software as expressly set out in Section 1.
+
+5. RESERVATION OF RIGHTS
+   The Software is licensed, not sold. Licensor retains all right, title, and
+   interest in and to the Software, including all intellectual property rights.
+
+6. DISCLAIMER OF WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE", WITHOUT WARRANTY OF ANY
+   KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
+   NON-INFRINGEMENT. YOU BEAR THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE
+   OF THE SOFTWARE.
+
+7. LIMITATION OF LIABILITY
+   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL LICENSOR
+   BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGES
+   WHATSOEVER, OR FOR ANY LOSS OF DATA, PROFITS, OR BUSINESS, ARISING OUT OF OR
+   IN ANY WAY RELATED TO THE USE OF OR INABILITY TO USE THE SOFTWARE, EVEN IF
+   ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+8. DATA AND PRIVACY
+   The Software runs locally against persistence You control and performs no
+   network communication by default. Licensor does not collect Your records.
+
+9. TERMINATION
+   This Agreement is effective until terminated. It terminates automatically if
+   You breach any term. Upon termination You must cease all use of the Software.
+   Sections 4 through 7 survive termination.
+
+10. GOVERNING LAW
+    This Agreement is governed by the laws of Singapore, without regard to its
+    conflict-of-laws principles.
+
+By installing or using the Software, You acknowledge that You have read this
+Agreement and agree to be bound by its terms.

package/README.md

@@ -0,0 +1,283 @@
+# inistate-core
+
+**A free, local runtime for FACTSOps workflows — the deterministic floor of the Inistate stack.**
+
+`inistate-core` runs governed state-machine workflows on persistence *you* control, driven over the [Model Context Protocol](https://modelcontextprotocol.io). One command, zero config, no account, no token, no network. Any MCP-compatible agent can drive it.
+
+It enforces the **present state** of your records — only legal transitions, validated forms, atomic writes — and nothing more. It is deliberately free of governance, authorization, and history.
+
+> **Core manages the _present state_ of your records. The Inistate Platform manages the _governed history_ of how that state changed** — together with the identity, authorization, and escalation a governed history implies.
+
+That line is not a limitation list; it is physics. Enforcing the present state needs only a record's current value — any store can hold that, which is why Core runs directly on your own data. Recording an accountable, append-only, actor-attributed past needs a governed store a plain table doesn't have. So Core holds no history of any kind — and that is the point.
+
+---
+
+## Quickstart — win the first 30 seconds
+
+```bash
+npx inistate-core
+```
+
+That's a complete deployment: a zero-config SQLite store at `~/.inistate/core.db`, serving the Inistate MCP tool surface over stdio.
+
+Wire it into any MCP client (Claude Desktop, Claude Code, Cursor, VS Code, …):
+
+```json
+{
+  "mcpServers": {
+    "inistate": {
+      "command": "npx",
+      "args": ["-y", "inistate-core"]
+    }
+  }
+}
+```
+
+No token. No workspace. No setup wizard. Point your agent at it and design a workflow, create entries, and drive transitions — all on local storage.
+
+---
+
+## Editions
+
+| | **Inistate Core** | **Inistate Core Plus** | **Inistate Platform** |
+|---|---|---|---|
+| Price | Free | **$9.99 one-time** | Paid (teams) |
+| For | make one data source AI-native | make your whole stack AI-native | govern human-AI operations |
+| Connectors | full connector support — **one backend type at a time** | **multiple backend types at once** | managed sync |
+| Also | deterministic runtime, valid transitions, typed forms | all Core + cross-source workflow modules, presets | people, roles, audit, UI, confidence/intention gating |
+
+> **Core makes one persistence layer AI-native. Core Plus connects many. Platform governs the organization.**
+
+- **Free** — make one *kind* of data source AI-native (any number of files/tables of that kind, e.g. several Excel workbooks).
+- **$9.99 once** — mix multiple *kinds* of source at once: Sheets, Notion, Airtable, SQLite, CSV, Excel, or your own adapter, side by side.
+- **Platform** — make the whole organization governed.
+
+Core is not crippled — it runs the full primitive on one backend type (and unlimited resources of that type). Core Plus is a one-time unlock for *mixing backend types*: set `INISTATE_CORE_PLUS_KEY` and map modules with `INISTATE_CORE_CONNECTIONS` (see [Connecting multiple tools](#connecting-multiple-tools--core-plus)). A single backend type never needs a license.
+
+---
+
+## What's inside the boundary
+
+| In Core (free, local) | In the Inistate Platform (paid) |
+|---|---|
+| Schema interpretation | Human collaboration, web/mobile UI |
+| **Present-state enforcement** (legal transitions) | Visual designer + app generation |
+| Typed activity forms + validation | Auth / roles, files |
+| Module design + validation | **Governed history & audit trail** |
+| Persistence-agnostic storage | **Confidence / intention gating** |
+| Descriptive `ai_hint` (*describe, never govern*) | Workspaces, the integrated AI Teammate |
+
+### The reliability invariants are the product
+
+Core gives away the hard parts so you don't hand-roll them. Each is property-tested, not just example-tested:
+
+- **Atomic transitions** — field writes and the state change commit together or not at all.
+- **Illegal-transition rejection** — no accepted operation can move an entry into a state its flows don't permit. *(This is the single most important guarantee.)*
+- **Idempotency** — replaying a submission with the same `idempotencyKey` applies the change at most once.
+- **Optimistic concurrency** — concurrent writers: exactly one wins; the other gets `CONFLICT`, no lost update.
+- **Crash durability** — a committed transition survives a process crash and restart (SQLite WAL).
+
+---
+
+## The tool surface
+
+Core serves the identical Inistate MCP tools. The runtime set is always on; module-design tools appear after `switch_mode("configure")`.
+
+**Served on Core (`Both`):** `list_modules`, `get_module_schema`, `get_module_canvas`, `list_entries`, `get_entry`, `get_form`, `submit_activity`, `submit_activities`, `design_workflow`, `validate_design`, `create_module`, `update_module`, `switch_mode`.
+
+**Platform-only tools** (`login`, `list_workspaces`, `set_workspace`, `get_entry_history`, `upload_file`, `download_file`, `request_upload_url`, `confirm_upload`) are **not silently absent** — calling one returns a structured capability message so your agent can explain the gap rather than fabricate a result:
+
+```json
+{
+  "error": "capability_unavailable",
+  "backend": "core",
+  "capability": "governed_history",
+  "message": "Governed history is not available on the local runtime. A local store keeps the current state of each record, not an accountable, append-only record of how it changed.",
+  "upgrade": "Connect to the Inistate Platform to enable governed history."
+}
+```
+
+`submit_activity` also accepts two reliability controls Core honours: `idempotencyKey` (safe retries) and `expectedVersion` (optimistic concurrency, read `version` from `get_entry`).
+
+---
+
+## Configuration
+
+Everything has a working default — a bare `inistate-core` is a valid deployment.
+
+| Setting | Env var | Default | Notes |
+|---|---|---|---|
+| Database | `INISTATE_CORE_DB` | `~/.inistate/core.db` | SQLite path, `memory`, or `<scheme>://…` for a registered adapter |
+| Multi-connection | `INISTATE_CORE_CONNECTIONS` | — | JSON map module → target. Mixing multiple backend types — needs Core Plus |
+| Core Plus license | `INISTATE_CORE_PLUS_KEY` | — | Unlocks mixing multiple backend types at once (one-time $9.99) |
+| Custom adapter | `INISTATE_CORE_ADAPTER` | — | Module that registers your own persistence (see below) |
+| Server mode | `INISTATE_MCP_MODE` | `runtime` | `runtime` or `configure` |
+| Logging | `INISTATE_LOG` | on | Set to `0` to silence stderr JSON logs |
+| Notion token | `INISTATE_NOTION_TOKEN` | — | Required for `notion://` targets |
+| Airtable token | `INISTATE_AIRTABLE_TOKEN` | — | Required for `airtable://` targets |
+| Google token | `INISTATE_GOOGLE_TOKEN` | — | OAuth2 access token, required for `sheets://` targets |
+
+### Storage schemes & connectors
+
+Selected by the scheme of `INISTATE_CORE_DB`. Built-in backends are dependency-free; standard connectors run a governed workflow **on your existing data**.
+
+| Scheme | `INISTATE_CORE_DB` example | Needs | Class / tier |
+|---|---|---|---|
+| `sqlite` *(default)* | `~/.inistate/core.db`, or any file path | — | Built-in — **full** present-state, durable (SQLite WAL) |
+| `memory` | `memory` | — | Built-in — non-durable (tests/fallback) |
+| `csv` | `csv://./tasks.csv` | — | Built-in (local file) — exposure tier (§5.5) |
+| `excel` | `excel://./book.xlsx?sheet=Sheet1` | optional `exceljs` | Standard (local file) — exposure tier (§5.5) |
+| `notion` | `notion://<databaseId>?module=Tasks&state=Status` | `INISTATE_NOTION_TOKEN` | Standard — exposure tier (§5.5) |
+| `airtable` | `airtable://<baseId>/<table>?module=Tasks&state=Status` | `INISTATE_AIRTABLE_TOKEN` | Standard — exposure tier (§5.5) |
+| `sheets` | `sheets://<spreadsheetId>/Sheet1?state=Status` | `INISTATE_GOOGLE_TOKEN` | Standard — exposure tier (§5.5) |
+
+Postgres is on the roadmap. Any other `<scheme>://…` resolves through a custom adapter you register with `INISTATE_CORE_ADAPTER` (community/custom tier — see [Bring your own persistence](#bring-your-own-persistence)). All standard connectors are available in Core; see [Notion & Airtable](#notion--airtable-built-in-exposure-tier) and [`examples/connectors.md`](examples/connectors.md) for every connector's full config.
+
+### Connecting multiple tools — Core Plus
+
+Core runs **one backend type at a time** — any number of resources of that kind (e.g. several Excel workbooks) is free. To connect **multiple kinds of backend/webservice at once** — routing different modules to different tools (e.g. `NEC` on Notion, `Tasks` in a CSV, `Leads` in Airtable) — unlock **Inistate Core Plus** (one-time $9.99): set `INISTATE_CORE_PLUS_KEY` and map modules with `INISTATE_CORE_CONNECTIONS`:
+
+```bash
+INISTATE_NOTION_TOKEN=ntn_… \
+INISTATE_CORE_PLUS_KEY=<your core-plus key> \
+INISTATE_CORE_CONNECTIONS='{"NEC":"notion://<dbId>?state=Status","Tasks":"csv://./tasks.csv","Leads":"airtable://<base>/<table>"}' \
+npx inistate-core
+```
+
+Each module gets its own connection, all in one runtime. Multiple resources of a *single* backend type — several Notion databases, or two Excel workbooks — count as one connector and stay free; the gate only fires when you mix *different* kinds of backend. Without a license, a mixed-type config prints a clear upgrade message and refuses to start (single-type mode is unaffected).
+
+---
+
+## Bring your own persistence
+
+The `StorageAdapter` interface is the **open seam**: SQLite (default) and an in-memory store ship built in, and you can plug in your own — a team Postgres, or an external substrate like Notion / Airtable / a spreadsheet — without forking. The engine owns correctness; your adapter owns storage. The one hard rule: `transaction(fn)` must be **all-or-nothing**, or the reliability invariants can't hold on your store.
+
+**For the binary** — point `INISTATE_CORE_ADAPTER` at a module that registers an adapter against a URL scheme, then select it with `INISTATE_CORE_DB`:
+
+```bash
+INISTATE_CORE_ADAPTER=./my-adapter.js \
+INISTATE_CORE_DB=mystore://./data \
+npx inistate-core
+```
+
+Your module exports either `register(api)` or a default `{ scheme, create }`:
+
+```js
+// my-adapter.js
+export function register(api) {
+  api.registerAdapter({
+    scheme: "mystore",
+    description: "My durable store",
+    create: (target) => new MyAdapter(target),
+  });
+}
+```
+
+**Embedding Core** in your own Node process:
+
+```ts
+import { createRuntime, loadConfig, registerAdapter } from "inistate-core";
+import type { StorageAdapter } from "inistate-core/adapter";
+
+registerAdapter({ scheme: "mystore", create: (t) => new MyAdapter(t) });
+const runtime = createRuntime(loadConfig());
+// runtime.backend → wire into createServer(); runtime.engine → drive directly
+```
+
+Implement `StorageAdapter` from `inistate-core/adapter` — `applyQuery` and `makeDocumentId` are exported so your adapter inherits identical query/document-id semantics (and passes the shared conformance suite). A complete, copy-pasteable reference adapter that persists to a single JSON file with atomic commits is in [`examples/json-store-adapter.ts`](examples/json-store-adapter.ts).
+
+### Notion & Airtable (built-in, exposure tier)
+
+Core ships reference adapters that run governed workflows **on top of your existing Notion databases or Airtable tables** — the friendliest on-ramp: keep your board, watch the engine block an illegal move on your own data. One Core instance can back **many modules**, each bound to its own table.
+
+```bash
+# Notion — single database → one module (each page is an entry; a Status property holds the state)
+INISTATE_NOTION_TOKEN=secret_xxx \
+INISTATE_CORE_DB="notion://<databaseId>?module=Tasks&state=Status" \
+npx inistate-core
+
+# Notion — multiple databases → multiple modules
+INISTATE_NOTION_TOKEN=secret_xxx \
+INISTATE_CORE_DB="notion://?LeaveRequests=<db1>&Expenses=<db2>" \
+npx inistate-core
+#   …or map them with INISTATE_NOTION_DATABASES='{"LeaveRequests":"db1","Expenses":"db2"}'
+
+# Airtable — single table → one module
+INISTATE_AIRTABLE_TOKEN=pat_xxx \
+INISTATE_CORE_DB="airtable://<baseId>/<tableIdOrName>?module=Tasks&state=Status" \
+npx inistate-core
+
+# Airtable — many tables in one base → many modules
+INISTATE_AIRTABLE_TOKEN=pat_xxx \
+INISTATE_CORE_DB="airtable://<baseId>?Tasks=<tbl1>&Leads=<tbl2>" \
+npx inistate-core
+#   …or map them with INISTATE_AIRTABLE_TABLES='{"Tasks":"tbl1","Leads":"tbl2"}'
+```
+
+Create each Core module with the **same name** you mapped (`create_module({ name: "LeaveRequests", … })`); that module's entries then live in its bound table. They use **your own credentials** (opt-in, never the default). How they work, honestly: Core hydrates each substrate's rows into a per-module in-memory cache at startup, **enforces present-state against that cache** (so illegal transitions are rejected through Core), and **mirrors committed changes back to each table** with a best-effort, ordered write-back — failures are logged, never hidden.
+
+**What's stored where.** Entry *records* live in the substrate (Notion/Airtable). The things a table can't express — your **module definitions** (states, activities, flows) and the **idempotency map** — persist in a small **SQLite meta sidecar** by default (`~/.inistate/<scheme>-<id>.db`, one per database/base), so a restart rehydrates records from the substrate and reloads the schema from SQLite without re-creating the module. Override the location with `?meta=<path>`, or use `?meta=memory` for an ephemeral meta store.
+
+**Schema changes are additive.** Your module's `information` fields + the state column are a subset of the connecting table's columns. `create_module`/`update_module` reconcile that **add-only**: a new field **adds** a column to the substrate (a Notion property via `PATCH /databases`, or an Airtable field via the Metadata API — which needs a PAT with `schema.bases:write`), and missing select options are merged in. Core **never drops** a column — removing a field from the schema just stops mapping to it; the column stays in your table, untouched. Provisioning is best-effort (a failure, e.g. a missing Airtable scope, is logged, not fatal — enforcement still holds against the cache). Disable it entirely with `?provision=off` to leave your table structure alone.
+
+Build your own substrate adapter by implementing a small async `SubstrateDriver` (`list` / `create` / `update` / `remove`, plus optional add-only `ensureColumns`) and reusing `ExternalSubstrateAdapter` — see [`src/storage/external/`](src/storage/external/).
+
+> **Two honest guarantee tiers (§5.5).** Core's own store (SQLite/Postgres) gives a full present-state guarantee, including against out-of-band corruption within the transactional boundary. An external substrate (Notion/Airtable/Sheets) holds enforcement *through Core*, but out-of-band hand-edits are possible — so the guarantee softens to "no illegal move *through Core*". Label that tier; attribute the limit to the substrate.
+
+---
+
+## Scaffold a schema from an existing table
+
+Already have a Notion database, Airtable table, or SQLite table? Generate a starter FACTSOps module schema from it — columns become typed fields, and a detected status column becomes states:
+
+```bash
+inistate-core scaffold notion://<databaseId>            # needs INISTATE_NOTION_TOKEN
+inistate-core scaffold airtable://<baseId>/<table>      # needs INISTATE_AIRTABLE_TOKEN
+inistate-core scaffold ./core.db --table leave_requests # local SQLite, no creds
+
+# pipe the schema straight to a file (guidance prints to stderr, schema to stdout)
+inistate-core scaffold ./core.db --table leave_requests --name "Leave Requests" > module.json
+```
+
+It prints a `ModuleSchema` to stdout and a validation summary + next steps to stderr. Override with `--name <Module>` and `--state <Column>`. Core deliberately leaves `activities`/`flows` empty — it can't infer the *governed transitions* a plain table doesn't express; defining those is the value Core adds. Finish the schema (e.g. with `design_workflow` for a pattern), `create_module`, then point Core at the same substrate and illegal moves are rejected.
+
+The same thing is available to an agent over MCP as the **`scaffold_module`** tool (configure mode — `switch_mode` to `configure`), designed so the user and the agent design the schema **together**. One container (a SQLite database, an Airtable base, a Notion workspace) often holds several tables — so the tool discovers them first and you map the chosen ones, each as its own module:
+
+1. **Discover** — call with just `source` pointed at the container: a SQLite database path, `airtable://<baseId>` (no table), or a bare `notion://`. It returns `{ discovery: true, tables: [{ name, id?, columns, rows?, hasState, scaffold_source }] }` so the agent can show what's there and ask the user which one(s) to model.
+2. **Draft** — call again with a chosen table's `scaffold_source` as `source` (or a SQLite `table`), plus optional `name` / `state`. It returns `{ schema, validation, suggestions }` — columns become typed fields, a detected status column becomes states.
+3. **Refine** — confirm the inferred field types with the user, then define `activities`/`flows` (e.g. via `design_workflow`).
+4. **Create** — `validate_design → create_module`, then point Core at the same data.
+
+Network targets read `INISTATE_NOTION_TOKEN` / `INISTATE_AIRTABLE_TOKEN` from the environment — tokens are never passed as tool arguments. Listing an Airtable base's tables uses the Metadata API, which needs the token's `schema.bases:read` scope; single-table scaffolding does not.
+
+Programmatic equivalent: `import { introspectSqlite, scaffoldModule } from "inistate-core"` (or `introspectTarget` to dispatch by URI).
+
+## Upgrading to the Platform
+
+```bash
+npx inistate-core connect
+```
+
+Moving to the Inistate Platform is a **backend swap, not a migration** — the same schema, the same MCP tools, re-pointed from the local engine to the Platform API. You *gain* people, UI, governed history, authorization, and the Teammate. Your workflows, vocabulary, and agent integrations carry over unchanged. A team can run real production on local Core forever and never pay — that is intended.
+
+---
+
+## Development
+
+```bash
+npm install      # installs deps and builds
+npm run build    # tsc → build/
+npm test         # vitest: invariants, conformance, capability, boundary, durability, end-to-end MCP
+npm run scan     # forbidden-symbol boundary scan over the engine + storage
+npm run check    # build + scan + test (the full gate)
+```
+
+The engine and storage adapters are kept clean of governance/UI/history concepts by a **forbidden-symbol scan** enforced in CI (`scan`). The shared **conformance suite** runs the same transition scenario against every storage backend (including a developer-style custom adapter) and asserts identical outcomes — the guard against semantic drift.
+
+---
+
+## License
+
+`inistate-core` is **free to use** but **not open source**. It ships under a proprietary free-use EULA (see [LICENSE](LICENSE)): run it anywhere, forever, at no cost — including in production — but the engine source is closed and no patent rights are granted. The embedded Inistate schema and MCP server are separately published under MIT.
+
+© GNEY SOFTWARE PTE LTD.