@intentic/engine 1.310.0 → 1.311.0

package/README.md

@@ -1,28 +1,35 @@
-# @intentic/engine
-
-The stateless **reconcile engine**. It walks a `DesiredStateGraph` in dependency order and converges it through the **Provider SPI**: never constructing providers itself, only consuming a `ResourceType → Provider` map. Depends on [`@intentic/graph`](../graph) + [`@intentic/resources`](../resources); the real providers live in [`@intentic/providers`](../providers).
-
-## Responsibilities
-
-- `apply`, converge once: per node, `read` → `diff` → `create`/`update`/`noop`, gating on readiness.
-- `plan`, dry run: classify every node without mutating infra.
-- `reconcile`: loop apply→read until a plan reads all-noop ("state reads true"), returning a `ConvergeResult`.
-- Define the **Provider SPI** the rest of the system implements: `Provider`, `Providers`, `Observed`, `DiffResult`, `ProviderContext`.
-- Emit structured `EngineEvent`s (for the CLI's ndjson/json output) and handle readiness, orphans, and pruning.
+# engine
+
+The stateless reconcile engine that plans, applies and prunes a desired-state graph by asking each resource's provider what exists in live infrastructure.
+
+```mermaid
+flowchart LR
+    cli["cli<br/>plan · apply · destroy"] --> engine(["engine"])
+    engine -- "each node, in order" --> read["provider.read"]
+    read -- "absent" --> create["apply: create"]
+    read -- "inputs changed" --> update["apply: update"]
+    read -- "matches" --> noop["noop"]
+    create --> ready["readyWhen probe<br/>outputs → store"]
+    update --> ready
+```
+
+- There is no state file. A provider finds its resource by the `intentic.id` stamp; a stamped `intentic.hash` that differs from the node's inputs forces an update before the provider's own `diff` is consulted.
+- `apply` walks the graph in dependency order, one node at a time, and stores each node's outputs so later `$ref` inputs resolve. `plan` does the same reads without mutating. `reconcile` alternates the two until a plan reads all noop, bounded by `maxIterations`.
+- `prune` deletes what the previous artifact declared and the current one lacks, in reverse order with the old inputs. `collectOrphans` and `pruneOrphans` catch stamped resources no graph mentions. `applyMoves` re-stamps renamed resources first so they are not recreated.
+- The engine constructs no providers. Callers pass a `Providers` map from [providers](../providers), or `createFakeProviders` for an in-memory world in tests.
+- Progress leaves as structured `EngineEvent`s; the CLI renders them and the daemon tails them.
 
 ## Key files
 
-- [src/reconcile/apply.ts](src/reconcile/apply.ts) / [src/reconcile/plan.ts](src/reconcile/plan.ts) / [src/reconcile/reconcile-loop.ts](src/reconcile/reconcile-loop.ts): the converge/dry-run/loop logic.
-- [src/provider.ts](src/provider.ts) / [src/types.ts](src/types.ts): the SPI and engine types (`Provider`, `DiffResult`, `EngineConfig`, `Step`, `Orphan`).
-- [src/readiness.ts](src/readiness.ts): `httpProbe` / `waitReady` (readiness gates), and `pollUntil`, the one waiting loop every "is it up yet" in the engine and the providers is written on.
-- [src/resolve-inputs.ts](src/resolve-inputs.ts): resolve refs/secrets into concrete provider inputs.
-- [src/reconcile/orphans.ts](src/reconcile/orphans.ts) / [src/reconcile/prune.ts](src/reconcile/prune.ts) (drift cleanup; [src/providers](src/providers)) `createFakeProviders` (in-memory SPI for tests).
-
-## How it fits
-
-The execution core. `state-resolver` produces the graph; `providers` supplies the concrete SPI map; the `cli` wires them together and runs `reconcile`. The engine stays infra-agnostic: all I/O is behind the SPI.
+- [src/provider.ts](src/provider.ts) — the `Provider` contract: `read`, `diff`, `apply`, and optional `list`, `delete`, `restamp`.
+- [src/reconcile/apply.ts](src/reconcile/apply.ts) — one converge pass over the graph.
+- [src/reconcile/reconcile-loop.ts](src/reconcile/reconcile-loop.ts) — apply then plan until nothing is left to do.
+- [src/reconcile/reconcile.ts](src/reconcile/reconcile.ts) — provider lookup and the stamped-hash drift check.
+- [src/reconcile/prune.ts](src/reconcile/prune.ts) — removal of dropped nodes and orphans.
+- [src/providers/fake.ts](src/providers/fake.ts) — in-memory providers that prove a second apply is a noop.
 
-## Conventions & gotchas
+## Commands
 
-- The engine never imports `providers`: it takes a `Providers` map as input, so it can run against fakes.
-- `diff` must be **pure** (read does the I/O); apply is the only mutating step. `EngineEvent` is part of the public contract for embedders. See [ARCHITECTURE.md](../../ARCHITECTURE.md).
+```sh
+pnpm --filter @intentic/engine test
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/engine",
-  "version": "1.310.0",
+  "version": "1.311.0",
   "description": "Stateless reconcile engine: plan/apply, the Provider SPI, and the reconcile loop.",
   "license": "MIT",
   "type": "module",
@@ -30,13 +30,13 @@
     }
   },
   "dependencies": {
-    "@intentic/base": "1.310.0",
-    "@intentic/graph": "1.310.0",
-    "@intentic/resources": "1.310.0",
+    "@intentic/base": "1.311.0",
+    "@intentic/graph": "1.311.0",
+    "@intentic/resources": "1.311.0",
     "tslib": "2.8.1"
   },
   "devDependencies": {
-    "@intentic/sdk": "1.310.0",
+    "@intentic/sdk": "1.311.0",
     "@intentic/testing": "0.0.0",
     "@intentic/tsconfig": "0.0.0",
     "@types/bun": "1.4.0",