Xyn Seed Deep Dive: From Intent to Execution (Plan-Always, Postgres-First)

Xyn Seed (xyn-seed) is the smallest deployable nucleus of Xyn: the system responsible for turning intent into execution safely, with full auditability. At a high level, Seed implements a deterministic control loop: Intent → Compile → Plan → Apply → Observe → Reconcile In earlier iterations, we summarized the loop as: Event → Blueprint → Agent → Action → Audit That’s still true — but it’s incomplete. The modern framing reflects what Seed actually guarantees: no direct mutation without a plan, and no invisible execution. This article is a technical deep dive into: - the Postgres-first architecture - the core runtime pipeline (events → runs → steps → artifacts) - deterministic planning and reconciliation - composition via Solution Blueprints, Modules, Capabilities, and Bundles - economic observability primitives (Footprints + Impressions) Repo: xyn-seed https://github.com/Xyence/xyn-seed How to read the xyn-seed repo (recommended order) If you want to follow along in code while reading this article, this is the best path: - README.md — Mission, quick start, architecture overview. - xyn_seed_implementation_plan.md — Design spec: runtime pipeline, artifacts, audit spine. - IMPLEMENTATION_SUMMARY.md — Practical snapshot: what exists now vs next. - METRICS_IMPLEMENTATION.md — Metrics direction that extends naturally into Footprints + Impressions. - core/ — Runtime: API, models, execution engine, storage boundaries. - scripts/ + compose.yml + Dockerfile — Minimal local infrastructure. - xynctl — Local-first bootstrapper / runner. Why “Postgres-first”? We refer to Seed as Postgres-first because Postgres is the primary system of record in v0: - events are persisted first - runs and steps are recorded as the executor progresses - artifacts are written with durable metadata - footprints and impressions attach to the same audit spine - reconciliation reads from the same truth store This yields three critical advantages early on: 1. Transactional correctness (atomic state transitions) 2. Simple query surface (UI reads from one store) 3. Minimal operational weight (no Kafka/consumers day one) Postgres-first does not mean Postgres-forever. It means: start with the simplest durable substrate, and preserve an evolution path to a dedicated event log via an outbox/dispatcher. Part I — The Control Plane Engine Seed’s core responsibility: safe change Seed exists to prevent a familiar failure mode: “An agent ran some tools and now the infrastructure is different, but nobody knows what happened.” Seed ensures that every mutation is: - preceded by a deterministic plan - captured as a durable operation record - observable via status + reconciliation That’s the difference between “automation” and a “control plane.” Architecture at a glance (Seed execution loop) Diagram 1 — Seed core loop (plan-always spine) flowchart TB A["Signal Ingress<br/>(webhook / api / poller / human)"] --> B["Event Store<br/>(events table)"] B --> C["Resolver<br/>(match triggers / policies)"] C --> D["Compiler<br/>(intent -> executable specs)"] D --> E["Planner<br/>(diff + actions)"] E --> F["Plan Review Gate<br/>(optional)"] F --> G["Applier<br/>(backend execution)"] G --> H["Operation Log<br/>(operations + logs)"] G --> I["Status & Reconciler<br/>(observed vs desired)"] D --> J["Artifacts Store<br/>(audit outputs)"] G --> J I --> J Key principle: the plan is the boundary between intent and mutation. The durable primitives (what makes Seed “real”) Seed is built around a few foundational objects — these are the audit spine. 1) Event (immutable) Everything begins as an Event. This normalizes input from: - external systems (webhooks) - internal systems (pollers, schedulers) - humans (UI/API) The moment the event is written, the system becomes auditable: “This happened.” 2) Run (execution instance) A Run is the execution instance of a compiled intent against an event/context. Runs are durable and queryable; they become the unit of accountability. 3) Step (bounded primitives) Steps are deliberately few and composable, e.g.: - agent_task — reasoning/planning/generation - action_task — execution against tools - gate — approvals - transform — pure mapping/formatting This is a design constraint: few primitives, high expressiveness. 4) Artifact (durable output) Artifacts are not “logs sprinkled everywhere.” They are first-class outputs: - logs - reports - downloads - structured JSON payloads - proofs Artifacts are what makes auditability concrete. Part II — Composition: Blueprints → Modules → Bundles This is the biggest evolution since early versions of Seed. Originally, the focus was “Blueprints run from events.” Now, Xyn explicitly supports decomposition into reusable building blocks. Solution Blueprints A Solution Blueprint defines an end-to-end outcome: - what the solution should do - what capabilities it requires - what constraints/policies apply - what bundle(s) should be produced Solution Blueprints are intended to be: - reusable - environment-agnostic - capability-driven (not implementation-bound) Modules A Module is the smallest independently versioned and releasable component. Module examples: - adapter.mikrotik-ztp - adapter.omci-voltha - ui.ems-console - domain.managed-bundle-model Modules expose interfaces (API/event/schema) and provide capabilities. Capability Contracts A Capability is a named intent contract. Solution Blueprints require capabilities. Modules provide capabilities. This decouples solutions from implementations. Bundles A Bundle is a deployable package assembled from modules. A bundle is what gets installed into an Xyn instance. Diagram 2 — Composition chain (solution intent to deployable bundle) flowchart TD SB["SolutionBlueprintSpec<br/>(solution intent)"] --> CAP["Capabilities Required<br/>(profiles + constraints)"] CAP --> MR["Module Registry<br/>(resolve + score)"] MR --> MOD["ModuleSpecs<br/>(versioned components)"] MOD --> BND["BundleSpec<br/>(deployable package)"] BND --> REL["ReleaseSpec<br/>(deploy-time intent)"] REL --> RUN["RuntimeSpec<br/>(backend-aligned intent)"] In other words: Blueprints explain what. Modules explain how. Bundles explain what ships. ReleaseSpecs explain what runs. How Seed uses this composition model Seed doesn’t just “run blueprints.” Seed compiles solution intent into executable intent: 1. validate blueprint specs (contracts) 2. resolve capabilities → module selections 3. assemble bundle 4. compile bundle → release specs 5. generate plan 6. apply + reconcile This is what makes it safe, deterministic, and scalable. Part III — Planning, Applying, Reconciling (The Control Plane) Planning (diff + actions) A ReleasePlan is created before any mutation occurs. Plans include: - list of actions (create/update/delete/noop) - diffs and artifacts (compiled specs, rendered manifests) - references to versions/revisions This is where “plan-always” becomes enforceable. Applying (backend execution) Seed then applies the plan using a backend adapter: - Docker Compose today - Kubernetes later The apply step produces an Operation, a durable record of execution. Reconciling (drift correction) Reconciliation is where Seed becomes a real control plane: - inspect observed state - compare to desired - update ReleaseStatus - optionally emit drift plans Diagram 3 — Execution lifecycle (plan/apply/status) sequenceDiagram autonumber participant Studio as xyence-web Studio participant Seed as xyn-seed API participant Backend as Backend (Compose/K8s) participant Ops as Operation Store participant Status as Status/Reconciler Studio->>Seed: POST /plan (SolutionBlueprintInstance) Seed->>Seed: compile -> bundle -> release -> runtime Seed-->>Studio: ReleasePlan Studio->>Seed: POST /apply (plan_id) Seed->>Ops: Operation(running) Seed->>Backend: apply runtime manifests Backend-->>Seed: results Seed->>Ops: Operation(succeeded) loop observe Status->>Backend: inspect Backend-->>Status: observed state Status-->>Seed: ReleaseStatus update end Part IV — Footprints & Impressions (Economic Observability) Footprints and Impressions are still important — but they are now best understood as part of the same audit spine. They attach to: - runs - steps - actions - artifacts Footprints (measured consequence) A Footprint is a measurable consequence: - tokens in/out - wall clock duration - bytes in/out - retries/errors - derived $ estimate (optional) Footprints are append-only facts. Impressions (derived meaning) An Impression is an interpretive label: - severity = high - customer_visible = true - billing_class = billable - anomaly = true Impressions can be rule-derived (v0) and later agent-enriched (v1+). Why split? Because measurements must stay honest, and meaning must stay adaptable. Diagram 4 — Footprints and impressions attach to the audit spine flowchart LR E[(Event)] R[(Run)] S[(Step)] A[(Action)] AR[(Artifact)] F[(Footprints)] I[(Impressions)] E --> R --> S --> A --> AR S --> F A --> F AR --> F F --> I R --> I Where to emit footprints (hook points) Footprints should be emitted only at runtime boundaries: 1. step lifecycle wrapper 2. LLM invocation wrapper 3. tool invocation wrapper 4. artifact persistence 5. run lifecycle wrapper This keeps economics observable without contaminating business logic. Where to compute impressions Recommended minimal implementation: - compute impressions at run.finalize() - derive from footprints + outcomes - persist on the run Then later: - agent classifier enriches impressions - policy engine governs decisions Part V — Multi-domain topology (federation readiness) Xyn assumes plural realities: multiple environments, multiple systems, multiple trust domains. Seed doesn’t require federation on day one — but it must not block it. Diagram 5 — Multi-domain topology + evolution path flowchart LR subgraph A["Domain A — Xyn Instance"] A1[(Events)] A2[(Runs)] A3[(Artifacts)] A4[(Footprints)] end subgraph B["Domain B — Xyn Instance"] B1[(Events)] B2[(Runs)] B3[(Artifacts)] B4[(Footprints)] end subgraph P["Partner Domain — Xyn Instance"] P1[(Events)] P2[(Runs)] P3[(Artifacts)] P4[(Footprints)] end A -->|"Federation Connector<br/>(policy + scope)"| P B -->|"Federation Connector<br/>(policy + scope)"| P Key principle: Federation does not collapse boundaries. It makes them explicit, inspectable, and governable. What comes next (implementation-driven) The near-term direction is clear: 1. Module Registry + Capability Catalog - deterministic decomposition - capability-driven selection 2. Bundle assembly as first-class - Bundles become the “install unit” - compatibility matrices become enforceable 3. Plan-always everywhere - releases, modules, bundles all become plan/apply governed 4. Economic observability - footprints at runtime boundaries - deterministic impressions at finalize - agent enrichment later Code and docs Repo: https://github.com/Xyence/xyn-seed - Implementation plan: xyn_seed_implementation_plan.md - Metrics direction: METRICS_IMPLEMENTATION.md - Current summary: IMPLEMENTATION_SUMMARY.md