Constructive realization

How Definition, Element, Realization, Constraint, and Validation fit the Pico story.

This page is the course-facing reference for the academy’s small constructive-realization vocabulary. It is written for learners and course authors working in the Pico course; the underlying contract lives in templates/README.qmd (in-repo scaffold, not published as a learner page; Phase 1).

Phase 1 is documentation and metadata only. Nothing here changes how a Pico is built; it names the concepts you are already using so lessons, labs, and metadata can point at them consistently.

The five terms

  • Definition — what an artifact is supposed to be: its purpose, intent, and expected outcome. In this course, a Pico’s Rules together with the surrounding lesson framing state a Definition.
  • Element — the concrete realized thing. In this course, a running hello-world-pico produced by the pipeline is an Element.
  • Realization — the constructive path from Definition to Element. In this course, the Rules → Parser → Composer → Pico pipeline is the Realization, and the Hello Pico lab records it step by step.
  • Constraint — a condition a valid Element must satisfy (for example: “the Pico responds to the hello event”, “the Rules parse without error”).
  • Validation — an executable or observable check that tests an Element against its Constraints (for example: a lab’s verify.sh, a course quiz, or an end-to-end lab walkthrough).

Mapping onto the Pico pipeline

The pipeline you already know maps cleanly onto the vocabulary:

Rules  ─────▶  Parser  ─────▶  Composer  ─────▶  Pico
(Definition)   (Realization)   (Realization)     (Element)
  • Rules carry the Definition of the Pico you intend to build.
  • Parser + Composer are the Realization: the constructive path that turns a Definition into an Element.
  • Pico (for example hello-world-pico) is the Element.
  • Constraints are the conditions the produced Pico must meet.
  • Validations are the checks — lab verifications, quizzes, observable behavior — that confirm the Element satisfies its Constraints.

Mapping onto compose → construct → behave

The academy’s three-layer story — Crossplane composes, Sandcastle constructs, Picos behave — is a story about Realization at three different scales:

Layer Constructive-realization view
Crossplane composes Realization by composition from sub-elements; a composed resource is the Element.
Sandcastle constructs The bounded engineering environment inside which Realizations safely run and produce Elements.
Picos behave The Elements themselves at runtime; their behavior is the observable evidence of Realization.

Concretely, in this course:

  • The Pico course teaches how a single Pico Element behaves.
  • The Crossplane course teaches how such Elements are composed on a control plane.
  • The Sandcastle course teaches the construction environment inside which Realization happens safely.

Where the terms show up in course material

You will most often encounter these concepts in the places you already work:

  • Course and lesson index.qmd — typically states a Definition (learning objectives, what the produced artifact is).
  • lab.qmd and the shared labs/ — typically records a Realization and the Element it produces.
  • metadata.yaml — the machine-readable side of the same story. The Phase 1 fields (constructive_role, realizes, constraints, validated_by, realization_pattern) are optional and additive; see templates/README.qmd (in-repo scaffold, not published as a learner page) for the full contract.
  • quiz.qmd and lab verifications — natural places for Validations that check an Element against its Constraints.

Authoring guidance for this course

  • Prefer natural-language Constraints in prose and named Validations (a verify.sh, a quiz question, an observable behavior) over formal schemas.
  • When a lesson produces a named artifact, treat that artifact name as the Element identity; a downstream lab realizes the same Definition when it lists it under realizes in its metadata.
  • Do not retrofit existing pico lessons or labs to the new metadata fields as part of this reference — the Phase 1 fields are optional and sit alongside existing metadata.

Hands as a governed extension

Part 3 introduces Hands — the controlled mechanism through which a Pico acts on the world. Hands slot into the same constructive vocabulary rather than sitting outside it, and they line up with the Phase 7 runtime/control-surface contract in templates/README.qmd (in-repo scaffold, not published as a learner page).

The mapping is:

Hands concept Constructive-realization view
Capability (e.g. github.issue.create) A Definition of an action the Pico is meant to be able to perform, stated in a Rule.
HandsProvider (ComposioHands, …) A Realization step: the constructive path from a Capability Definition to an executed act.
ActionRequest + ExecutionContext The Definition of one specific attempt to act, carrying identity, authorization, and Policy.
Hand execution on a HandsProvider The Realization producing the acted-upon Element (an issue created, a resource applied).
Policy A Constraint on the ActionRequest — the same Phase 1 Constraint concept, scoped to a Capability.
Evidence and Action Events Validations and Observations: they record whether the executed action satisfied its Constraints.

Hands stay provider-neutral: Pico rules name Capabilities, not provider tool names, so the HandsProvider Realization step can be swapped (Composio, Kubernetes, local, MQTT, physical) without changing the Capability Definitions the Pico depends on. This mirrors the Phase 7 rule that ControlSurfaces and runtime environments must not replace or bypass the constructive chain.

Nervous system as a governed extension

The course also introduces a Nervous System — the provider-neutral communication fabric through which a Pico senses, communicates, coordinates, and interacts with other Picos, devices, and services. The Nervous System sits after Hands in the Pico progression and is distinct from Brain/Mind, Hands, and Voice: Brain/Mind decides whether to act, Hands decide how to act on external systems, Voice decides what to communicate outward, and the Nervous System is the transport-neutral fabric those messages travel through.

Like Hands, the Nervous System slots into the same constructive vocabulary rather than sitting outside it, and it lines up with the Phase 7 runtime/control-surface contract in templates/README.qmd (in-repo scaffold, not published as a learner page).

The mapping is:

Nervous System concept Constructive-realization view
Pico Agent Transport A Realization step: the constructive path from a Nervous System message Definition to a delivered message.
Message Envelope The Definition of a single message: type, identity, correlation, timestamp, payload — stated independently of wire format.
Observation (course-scoped) A runtime-captured Observation in the Phase 7 sense; a candidate input to Feedback that MAY refine a Definition.
Event A named runtime occurrence carried through a Phase 7 Channel as a typed EventType value.
Command The Definition of a requested action; the receiving Pico’s Rules provide its Realization, and Policy is its Constraint.
Delegation The Definition of a mission handed to another Pico; the delegate’s Rules and Policy are its Realization and Constraints.
Result A Validation of a Command or Delegation: the observable outcome recorded against the original request’s Constraints.
Presence A runtime-captured Observation about a Pico’s transport availability; not a Capability claim.
Discovery A Definition-facing lookup of what Capabilities are advertised; it does not by itself authorize invocation.
Topic Authorization A Constraint on the transport pathway an envelope may traverse.
Capability Authorization A Constraint on which Capabilities a specific Identity may invoke — the same Constraint concept Policy applies to Hands.

The Nervous System stays provider-neutral: Pico rules and Hands name Capabilities and Nervous System message types, not transport-specific identifiers, so the transport Realization step can be swapped (MQTT via EMQX, a future A2A binding, an in-process transport) without changing the Nervous System Definitions the Pico depends on. This mirrors the Phase 7 rule that ControlSurfaces and runtime environments must not replace or bypass the constructive chain, and the Hands rule that HandsProviders must not become the Pico’s semantic owner.

Identity, Authorization, Evidence, and Memory boundaries remain the same across Hands and the Nervous System:

  • Identity is required context on every envelope; the transport’s own client/session identifiers MUST NOT be treated as the Pico’s Identity.
  • Authorization is decided by Policy on the semantic layer; Topic Authorization at the transport is necessary but not sufficient, and a valid transport credential MUST NOT be treated as Capability Authorization.
  • Evidence records what a governed exchange did — the acting Pico, the requested Capability, the authorization decision, the lifecycle of the request — without carrying transport credentials or raw payloads.
  • Memory remains a Pico-side decision: an Observation or Event received through the Nervous System is not automatically Memory. The Pico’s Rules decide whether it becomes Evidence, a Memory candidate, or is discarded.

The existing Rules → Parser → Composer → Pico pipeline and the Part 3 · Hands contract remain unchanged; the Nervous System is an additive layer alongside them.

Out of scope on this page

This page intentionally does not:

  • Introduce a formal ontology, schema, or conformance checker.
  • Change the Pico pipeline, lesson layout, or lab format.
  • Retrofit existing courses, lessons, or labs to the Phase 1 fields.
  • Add HandsProvider SDKs, credentials, or external integrations; those are out of scope for the course contract and belong to separate provider-follow-up work.
  • Add transport SDKs, broker credentials, or a specific MQTT/EMQX deployment; the Nervous System contract names transport-neutral semantics and leaves broker adapters, credentials, and schema-enforcement tooling to separate follow-up work.

See the Glossary for one-line definitions of these terms and the course overview for how the pieces fit together. For a fully worked example that points each term at concrete Hello Pico material, see Hello Pico as a constructive exemplar.