Data products and plugins

This page follows one path: how data in a system you already run becomes evidence a decision can stand on, and how it reaches the people who make the call.

The path has a shape worth stating up front. Data enters through a connected data source, is shaped by a definition you author, is materialized into an instance, is frozen into an immutable record, and is then designated as evidence for something a phase must satisfy. Along the way it is drawn on screen by a plugin. Each of those words means one specific thing.

Connected data sources

Upstream of everything is a connected data source: a typed, reusable connection naming what sits on the other end of one of your systems and carrying how to reach it — a warehouse schema, an object store, an API.

Three properties matter to an architect evaluating this:

• A source is the connection, nothing more. It holds no queries and no product shape. Those live in the definitions that draw on it. Register the connection once — its type, its configuration, and a secret-store reference for its credentials, never plaintext — and every definition needing that system names the same source.
• Connections to your systems are read-only by contract. Nothing the platform does writes back through a connection to a customer-owned system. Only platform-owned stores are writable, and only through the governed operations below.
• Reuse is the point. Because the connection carries no query, one source can feed many products: one health signal, one credential path, many downstream uses.

Data products and their four tiers

A data product is how the platform holds data that matters to a decision: named, shaped, attributable, and — when it counts — frozen. One product passes through up to four tiers on the way from recipe to evidence, and knowing which tier you hold tells you what you can do with it.

You author exactly one of these: the definition. Everything else is produced from it.

Two facts carry most of the model. First, the tiers order by commitment, not by sequence — the common path runs definition to record directly, and the persistent instance is an optional draft stage for data you want to stage, refresh, and pin later. Second, there is exactly one way to freeze something, so the audit question “when did this become fixed?” always has one answer.

A useful analogy for anyone from a data background: the definition is a view definition, a persistent instance is a materialized view, and a record is a tagged snapshot.

Best practice is to freeze before consumption. Anything a person approves, a gate reads, or a later phase builds on should be a record first. Drafts are for authoring, not for evidence.

What a frozen record carries

Besides its payload, every record carries:

• A content hash — its identity by content. Two records with identical content share a hash, and nothing about a frozen record can change without changing its identity.
• A descriptor — its own declared shape: columns and types for a table, a declared schema for a structured document, a member manifest for a composite. You declare it, the platform validates the content against it at freeze time, and the two are sealed together.
• A parent, when the record extends an earlier record of the same product — the pointer that forms a revision chain.
• A purpose — the role this record plays in its phase. It is what keeps two same-shaped records in one phase distinguishable: a candidate list and a decision summary may both be tables, told apart by purpose.
• Where it was produced — the phase, cycle, and loop it came from. This is the coordinate later phases use to find it.
• Attribution and stamped facts — who or what produced it, and any facts recorded at write time, such as who approved something and when. Facts are stamped by the producer at the moment of the write, never inferred later.

Purpose vocabulary is configuration, not platform code: each phase objective declares the roles it expects, and you extend that vocabulary by editing the objective.

Kinds and composites

A data product’s kind is the shape of what it yields:

• table — rows with a declared column schema.
• json — a structured document with a declared schema; a decision summary or a chart specification.
• document — an opaque file carried by a content-bound handle; a PDF or an image.
• data-package and canvas — the two composites, which hold other products.

The two composites are not interchangeable, and the distinction is load-bearing:

A data-package is data that carries its own frozen provenance. A canvas is presentation that only points at what it shows.

A data-package composes data. Use it when several products must be read together as one coherent thing — a budget summary with its line items, an asset profile assembled from four systems. Its members are bound and resolved together, it can declare and validate relationships between its members so an orphaned reference fails rather than passing quietly, and when frozen it carries both an inline copy of each member’s data and a reference to the member’s frozen record. The copy makes it self-contained and portable — exactly what was seen. The reference makes it provably backed by citable records. It carries both, always.

A canvas composes presentation. It is a markdown document carrying slots, each naming a material to show, with the surrounding prose between them. A slot dereferences what it names at the moment the canvas renders, so each slot shows that material’s current state. A canvas never embeds data; it holds pointers. Its slots are independent, so one canvas can carry unrelated materials, including materials intended for different approvers on one scrollable surface.

A canvas is the more dynamic alternative to a hard-coded page: because it is data, agents can change what is shown as a decision develops, rewriting the prose and re-selecting the slots as the phase moves.

From record to evidence: designation

Freezing makes data durable. It does not make it relevant. Those are two separate acts on two separate axes:

work in progress  --promote-->  frozen record
                                     |
                                     | designate
                                     v
                              Decision Material

Promotion freezes. Designation binds. A Decision Material is a frozen record that has been explicitly bound to something a phase must satisfy before the cycle can advance. Most frozen records are never designated; they are working data. A phase gate reads only the designated ones.

Keeping the two acts separate is deliberate. It means a designation can be made — and audited — well after the freeze, and it means the question “what did this decision actually rest on?” has a precise answer rather than a directory listing.

Plugins: how data reaches the screen

A visualization plugin renders one data product instance. The host hands it the canonical value — declared shape plus payload — and the plugin draws its genre: a table, a chart, a record detail, a document, a form, a composite.

Kind is what a product is. Genre is how a plugin draws it. One kind can be drawn by more than one genre.

Plugins never see the tier. A transient preview, a working draft, and a frozen record all render through the same contract, so a surface built once works across the whole lifecycle. The consequence: rendering is a property of the data, not of the screen. The same candidate list draws as the same table on the analysis surface, in the collaboration pane, and inside a composite, because each is the same declared shape meeting the same genre.

Choosing what a surface shows

A render binding connects one plugin to one target — a draft instance or a frozen record — plus its rendering configuration. The target choice gives two behaviors: bind a draft instance for a fast-moving working view that is never citable, or bind a record (or a standing view over records) for a governed view where every state shown is frozen and citable.

For decision surfaces, bind by coordinate, not by identifier. A standing view selecting “this cycle, this phase, this purpose” resolves to the current state at that coordinate, so a surface always shows the right cycle’s data without ever choosing a record in the browser. Zero records at a coordinate is an explicit empty state; two conflicting records at one coordinate is an integrity error the platform surfaces rather than a guess the screen makes.

Write affordances: how a screen captures intent

People act on decision surfaces through write affordances — controls a plugin renders whose effect is a governed platform write. The division of labor is strict:

• The plugin emits typed intent. A form or an approval control builds a typed payload and hands it to the host. The plugin holds no credentials, no endpoints, and no write channel of its own. A plugin that needs credentials is mis-designed.
• The host owns the authenticated write. It composes the full record metadata and performs the write under the acting person’s identity. What lands is an ordinary data product, indistinguishable downstream from any other record.
• The act enters the record as itself. The record an affordance mints carries the acting person and the moment as stamped facts.

Every affordance’s effect decomposes into a small fixed vocabulary of writes and nothing outside it. That bounded vocabulary is what makes each affordance governable no matter what it looks like on screen.

Approval, walked through

Approval is the affordance worth following exactly, because it ties the composites, the freeze, and the gate together.

What gets approved is a material — a data product drawn by a plugin that carries an approval control. Usually that material is a data-package, but a single document record can be approvable too. The approval covers the content: everything the material comprises, across every frozen record inside it.

A canvas is never what gets approved. It is a presentation surface; it may scroll and may carry several approvable materials for different approvers. What is designated and what a gate reads is the material.

On approval, the host writes a new data-package. Its members are the approved content plus a new approval record capturing the approver, the timestamp, and any comments. That approval record names the frozen identity of the exact material that was signed, so nothing is lost when the package is assembled. Every member is frozen, enforced when the new package is itself frozen.

Then the phase agent designates it and the gate judges. A phase may require several approvals; each yields its own approved package. The gate validates them together — is each approval from the right person, holding the right authority, filling the role the phase declared? — and advances only if every one passes.

This split is what makes an approval evidence rather than interface state. The approved package is on the record whether or not the gate opens. A wrong person’s approval produces a record naming the wrong person, and the gate refuses it by name.

Where to go next

• Workstreams and phases — phase objectives, gates, and what evidence a gate will and will not accept.
• Agents and runtimes — who is doing the promoting and designating, and under what authority.
• Architecture overview — where records, drafts, and connections physically live in a deployment.