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