@cynodia/axiom-server 0.9.0-alpha.2 → 0.11.1-alpha.1

package/README.md

@@ -22,21 +22,37 @@ SQLite), `TransportAdapter` (in-process and HTTP), `ServerHost` for time, identi
 scheduling and authentication, and `IntegrationAdapter` for external systems. Nothing in
 an ApplicationGraph mentions HTTP, SQL, a route or an SDK.
 
-As of 0.8 this package also owns timed and event-driven execution: it schedules and
-dispatches `TriggerDef`s, records `integration-effect` intent atomically with the state
-write that requested it (the transactional outbox), dispatches an effect's committed
-intents to its `IntegrationAdapter` post-commit with retry, and translates verified
-webhook deliveries into semantic events. See
-[`docs/INTEGRATIONS.md`](https://github.com/cynodia/axiom/blob/main/docs/INTEGRATIONS.md),
-[`docs/EFFECTS.md`](https://github.com/cynodia/axiom/blob/main/docs/EFFECTS.md) and
-[`docs/TRIGGERS.md`](https://github.com/cynodia/axiom/blob/main/docs/TRIGGERS.md).
+This package also owns the parts of an application that only the authority can run:
+
+- **Timed and event-driven execution** (0.8) — scheduling and dispatching `TriggerDef`s,
+  the transactional outbox for `integration-effect` intent, post-commit effect delivery
+  with retry, and verified-webhook → semantic-event translation. See
+  [`docs/INTEGRATIONS.md`](https://github.com/cynodia/axiom/blob/main/docs/INTEGRATIONS.md),
+  [`docs/EFFECTS.md`](https://github.com/cynodia/axiom/blob/main/docs/EFFECTS.md),
+  [`docs/TRIGGERS.md`](https://github.com/cynodia/axiom/blob/main/docs/TRIGGERS.md).
+- **Inbound streams and binary storage** (0.9) — long-lived `SubscriptionDef` sources
+  feeding the event pipeline, and `StorageDef` object stores behind host blob transports.
+  See [`docs/SUBSCRIPTIONS.md`](https://github.com/cynodia/axiom/blob/main/docs/SUBSCRIPTIONS.md),
+  [`docs/STORAGE.md`](https://github.com/cynodia/axiom/blob/main/docs/STORAGE.md).
+- **The query layer** (0.10) — demand-driven `QueryDef` reads over authoritative data too
+  large to materialize, `DataProvider`s (`createMemoryDataProvider` / `createSqliteDataProvider`),
+  fingerprinted keyset cursors, and a principal/policy-scoped result cache. See
+  [`docs/QUERIES.md`](https://github.com/cynodia/axiom/blob/main/docs/QUERIES.md).
+- **Schema evolution** (0.11) — `planMigration` / `explainMigration`, the host-controlled
+  `executeMigration`, the durable `MigrationMetadataStore` and lease lock, keyset-batched
+  crash-resumable migration, memory and SQLite `MigrationRowStore`s, and the
+  `createAxiomServer` startup gate. See
+  [`docs/MIGRATIONS.md`](https://github.com/cynodia/axiom/blob/main/docs/MIGRATIONS.md).
 
 Main exports: `createAxiomServer`, `createMemoryPersistence`, `createSqlitePersistence`,
 `createServerHost`, `createDeterministicServerHost`, `createDirectTransport`,
 `createHttpTransport`, `createRemoteGateway`, `serveOverHttp`, `serveAxiomApplication`,
 `createFakeIntegrationAdapter`, `createHttpIntegrationAdapter`, `createTriggerRuntime`,
-`createEffectRunner`, `runConformanceFixture`, `runConformanceSuite`,
-`SERVER_DIAGNOSTIC_CODES`.
+`createEffectRunner`, `createMemoryDataProvider`, `createSqliteDataProvider`,
+`createMemoryMigrationStore`, `createSqliteMigrationStore`, `createMemoryRowStore`,
+`createSqliteRowStore`, `planMigration`, `explainMigration`, `executeMigration`,
+`getMigrationStatus`, `migrationAuthority`, `runConformanceFixture`, `runConformanceSuite`,
+`runQueryConformanceFixture`, `runMigrationConformanceFixture`, `SERVER_DIAGNOSTIC_CODES`.
 
 `serveAxiomApplication` is the whole deployment story: it serves the generated page at `GET /`
 and the semantic endpoint at `POST /axiom`, from one process, for any Axiom application. No
@@ -44,17 +60,26 @@ route, controller, handler or SQL statement is written by an application author.
 
 ### Portable artifacts
 
-`axiom.server.v1` is a frozen, language-independent contract, and this package ships what an
-implementation in another language needs to conform to it:
+The Server IR contract is versioned. **`axiom.server.v1` is frozen** — its bytes and
+semantics never change — but it is **not the current contract**: a document declares the
+oldest contract that can carry its vocabulary, computed from the document. The current
+contract is **`axiom.server.v7`** (0.11 schema-evolution vocabulary); `v1`–`v6` are frozen
+and shipped for compatibility. This package ships what an implementation in another language
+needs to conform:
 
 ```
-@cynodia/axiom-server/conformance                       the fixture manifest
-@cynodia/axiom-server/conformance/<name>.json           one fixture: IR, state, invocations, expectations
-@cynodia/axiom-server/schema/server-ir.v1.schema.json   JSON Schema for the frozen v1 IR
-@cynodia/axiom-server/schema/server-ir.v2.schema.json   JSON Schema for v2 (+ group, expression-ref)
-@cynodia/axiom-server/schema/server-ir.v3.schema.json   JSON Schema for v3 (+ integrations, effects, triggers, events)
-@cynodia/axiom-server/schema/server-ir.v4.schema.json   JSON Schema for v4 (+ invocation source, structured effect outcome)
-@cynodia/axiom-server/schema/protocol.v1.schema.json    JSON Schema for the protocol
+@cynodia/axiom-server/conformance                          the base fixture manifest
+@cynodia/axiom-server/conformance/<name>.json              one base fixture: IR, state, invocations, expectations
+@cynodia/axiom-server/conformance/queries/<name>.json      one query conformance fixture (axiom.conformance.v4)
+@cynodia/axiom-server/conformance/migrations/<name>.json   one migration conformance fixture (axiom.conformance.v5)
+@cynodia/axiom-server/schema/server-ir.v1.schema.json      JSON Schema for the frozen v1 IR
+@cynodia/axiom-server/schema/server-ir.v2.schema.json      v2 (+ group, expression-ref)
+@cynodia/axiom-server/schema/server-ir.v3.schema.json      v3 (+ integrations, effects, triggers, events)
+@cynodia/axiom-server/schema/server-ir.v4.schema.json      v4 (+ invocation source, structured effect outcome)
+@cynodia/axiom-server/schema/server-ir.v5.schema.json      v5 (+ subscriptions, storage, blob operations)
+@cynodia/axiom-server/schema/server-ir.v6.schema.json      v6 (+ queries, relationships, read policies)
+@cynodia/axiom-server/schema/server-ir.v7.schema.json      v7 (+ migrations, schema version + fingerprint) — current
+@cynodia/axiom-server/schema/protocol.v1.schema.json       JSON Schema for the protocol
 ```
 
 The fixtures are pure data. Running them requires no part of this implementation — which is

package/conformance/migrations/add-optional-field.json

@@ -0,0 +1,167 @@
+{
+  "conformance": "axiom.conformance.v5",
+  "name": "add-optional-field",
+  "covers": [
+    "spec11 §17",
+    "add optional field"
+  ],
+  "description": "Order.note is added as optional; existing rows stay valid without a rewrite.",
+  "serverIR": {
+    "contract": "axiom.server.v7",
+    "id": "migration-conformance",
+    "name": "Migration Conformance",
+    "version": "0.11.1-alpha.1",
+    "schemaVersion": 2,
+    "schemaFingerprint": "7e4d24d95c273ff084e7758508a02e35015d5db2ceda46ca61e7ee8a2c2a4929",
+    "migrations": [
+      {
+        "kind": "migration",
+        "id": "m_1_2",
+        "fromSchema": 1,
+        "toSchema": 2,
+        "operations": [
+          {
+            "id": "op_add_note",
+            "kind": "add-field",
+            "entityId": "entity_order",
+            "field": {
+              "id": "field_order_note",
+              "valueType": {
+                "kind": "optional",
+                "valueType": {
+                  "kind": "primitive",
+                  "primitive": "string"
+                }
+              }
+            }
+          }
+        ]
+      }
+    ],
+    "entities": [
+      {
+        "kind": "entity",
+        "id": "entity_order",
+        "identityFieldId": "field_order_id",
+        "fields": [
+          {
+            "id": "field_order_id",
+            "valueType": {
+              "kind": "primitive",
+              "primitive": "string"
+            }
+          },
+          {
+            "id": "field_order_total",
+            "valueType": {
+              "kind": "primitive",
+              "primitive": "number"
+            }
+          },
+          {
+            "id": "field_order_note",
+            "valueType": {
+              "kind": "optional",
+              "valueType": {
+                "kind": "primitive",
+                "primitive": "string"
+              }
+            }
+          }
+        ]
+      }
+    ],
+    "fields": {
+      "field_order_id": {
+        "entityId": "entity_order",
+        "field": {
+          "id": "field_order_id",
+          "valueType": {
+            "kind": "primitive",
+            "primitive": "string"
+          }
+        }
+      },
+      "field_order_total": {
+        "entityId": "entity_order",
+        "field": {
+          "id": "field_order_total",
+          "valueType": {
+            "kind": "primitive",
+            "primitive": "number"
+          }
+        }
+      },
+      "field_order_note": {
+        "entityId": "entity_order",
+        "field": {
+          "id": "field_order_note",
+          "valueType": {
+            "kind": "optional",
+            "valueType": {
+              "kind": "primitive",
+              "primitive": "string"
+            }
+          }
+        }
+      }
+    },
+    "states": [
+      {
+        "id": "state_entity_order",
+        "kind": "state",
+        "valueType": {
+          "kind": "collection",
+          "itemType": {
+            "kind": "entity",
+            "entityId": "entity_order"
+          }
+        },
+        "authority": "server"
+      }
+    ],
+    "actions": {},
+    "constraints": [],
+    "transitionConstraints": [],
+    "observableStateIds": [
+      "state_entity_order"
+    ]
+  },
+  "fromVersion": 1,
+  "sourceData": {
+    "entity_order": [
+      {
+        "field_order_id": "order-0000",
+        "field_order_total": 0
+      },
+      {
+        "field_order_id": "order-0001",
+        "field_order_total": 1
+      },
+      {
+        "field_order_id": "order-0002",
+        "field_order_total": 2
+      }
+    ]
+  },
+  "expect": {
+    "ok": true,
+    "status": "completed",
+    "targetData": {
+      "entity_order": [
+        {
+          "field_order_id": "order-0000",
+          "field_order_total": 0
+        },
+        {
+          "field_order_id": "order-0001",
+          "field_order_total": 1
+        },
+        {
+          "field_order_id": "order-0002",
+          "field_order_total": 2
+        }
+      ]
+    }
+  }
+}

package/conformance/migrations/add-required-field-with-default.json

@@ -0,0 +1,177 @@
+{
+  "conformance": "axiom.conformance.v5",
+  "name": "add-required-field-with-default",
+  "covers": [
+    "spec11 §18",
+    "add required field + default"
+  ],
+  "description": "Order.status is added as required; every existing row is populated with \"draft\".",
+  "serverIR": {
+    "contract": "axiom.server.v7",
+    "id": "migration-conformance",
+    "name": "Migration Conformance",
+    "version": "0.11.1-alpha.1",
+    "schemaVersion": 2,
+    "schemaFingerprint": "2c478dc5301786b76c6990e38e1659d621d7712fdfa785bf115b1275b9804877",
+    "migrations": [
+      {
+        "kind": "migration",
+        "id": "m_1_2",
+        "fromSchema": 1,
+        "toSchema": 2,
+        "operations": [
+          {
+            "id": "op_add_status",
+            "kind": "add-field",
+            "entityId": "entity_order",
+            "field": {
+              "id": "field_order_status",
+              "valueType": {
+                "kind": "primitive",
+                "primitive": "string"
+              },
+              "required": true
+            },
+            "populate": {
+              "kind": "literal",
+              "value": "draft"
+            }
+          }
+        ]
+      }
+    ],
+    "entities": [
+      {
+        "kind": "entity",
+        "id": "entity_order",
+        "identityFieldId": "field_order_id",
+        "fields": [
+          {
+            "id": "field_order_id",
+            "valueType": {
+              "kind": "primitive",
+              "primitive": "string"
+            }
+          },
+          {
+            "id": "field_order_total",
+            "valueType": {
+              "kind": "primitive",
+              "primitive": "number"
+            }
+          },
+          {
+            "id": "field_order_status",
+            "valueType": {
+              "kind": "primitive",
+              "primitive": "string"
+            },
+            "required": true
+          }
+        ]
+      }
+    ],
+    "fields": {
+      "field_order_id": {
+        "entityId": "entity_order",
+        "field": {
+          "id": "field_order_id",
+          "valueType": {
+            "kind": "primitive",
+            "primitive": "string"
+          }
+        }
+      },
+      "field_order_total": {
+        "entityId": "entity_order",
+        "field": {
+          "id": "field_order_total",
+          "valueType": {
+            "kind": "primitive",
+            "primitive": "number"
+          }
+        }
+      },
+      "field_order_status": {
+        "entityId": "entity_order",
+        "field": {
+          "id": "field_order_status",
+          "valueType": {
+            "kind": "primitive",
+            "primitive": "string"
+          },
+          "required": true
+        }
+      }
+    },
+    "states": [
+      {
+        "id": "state_entity_order",
+        "kind": "state",
+        "valueType": {
+          "kind": "collection",
+          "itemType": {
+            "kind": "entity",
+            "entityId": "entity_order"
+          }
+        },
+        "authority": "server"
+      }
+    ],
+    "actions": {},
+    "constraints": [],
+    "transitionConstraints": [],
+    "observableStateIds": [
+      "state_entity_order"
+    ]
+  },
+  "fromVersion": 1,
+  "sourceData": {
+    "entity_order": [
+      {
+        "field_order_id": "order-0000",
+        "field_order_total": 0
+      },
+      {
+        "field_order_id": "order-0001",
+        "field_order_total": 1
+      },
+      {
+        "field_order_id": "order-0002",
+        "field_order_total": 2
+      },
+      {
+        "field_order_id": "order-0003",
+        "field_order_total": 3
+      }
+    ]
+  },
+  "expect": {
+    "ok": true,
+    "status": "completed",
+    "targetData": {
+      "entity_order": [
+        {
+          "field_order_id": "order-0000",
+          "field_order_total": 0,
+          "field_order_status": "draft"
+        },
+        {
+          "field_order_id": "order-0001",
+          "field_order_total": 1,
+          "field_order_status": "draft"
+        },
+        {
+          "field_order_id": "order-0002",
+          "field_order_total": 2,
+          "field_order_status": "draft"
+        },
+        {
+          "field_order_id": "order-0003",
+          "field_order_total": 3,
+          "field_order_status": "draft"
+        }
+      ]
+    }
+  }
+}