# PortaShape System Model and Vocabulary

## Why a shared model is the product

PortaShape becomes coherent when every capability works from one representation of a digital system. Without that representation, control generation, runtime tuning, mapping, migration, validation, and documentation remain separate utilities. With it, they become different operations on the same graph.

The canonical PortaShape model is a **typed, semantic, provenance-aware graph of system elements and relationships**.

## Core objects

### System

A **system** is any bounded digital context PortaShape can inspect or affect. It may be a website, application, service, API, database, repository, design system, content platform, environment, user profile, workflow, brand system, animation engine, or composite of these.

A system declaration includes identity, adapter, environment, version, capabilities, permission scope, schema references, and connection metadata. Secrets are referenced, not embedded.

### Element

An **element** is anything meaningful within a system. Common element kinds include:

- value;
- object or record;
- schema or field;
- component or component property;
- design token or CSS declaration;
- route or content item;
- action or function;
- event or signal;
- asset;
- policy or validation rule;
- control or view;
- workflow or job;
- environment or deployment;
- user, role, or permission boundary.

### Value

A **value** is a typed piece of system state or configuration. It is the most common unit exposed, tuned, mapped, transformed, validated, and transferred.

A value should be describable by:

- stable identifier and path;
- human name and description;
- semantic role;
- data type and representation;
- current, default, proposed, and destination values where applicable;
- scope;
- authority owner;
- writer or mutation mechanism;
- lifecycle and persistence;
- constraints and allowed operations;
- sensitivity and permission requirements;
- provenance and observation time;
- confidence where discovered or inferred;
- control suggestions and display metadata.

### Relation

A **relation** is a typed edge between elements. Relation kinds include:

- contains;
- references;
- depends on;
- derives from;
- controls;
- renders;
- triggers;
- validates;
- conflicts with;
- maps to;
- translates to;
- transmutes into;
- synchronizes with;
- supersedes;
- was generated from.

Mappings are therefore not a separate data model. They are a specialized family of relations with execution semantics.

### Surface

A **surface** is an interactive projection of system elements. It may be a control panel, inspector, table, dashboard, editor, relationship map, component preview, timeline, workflow, or generated internal tool.

A surface does not own system truth simply because it displays or edits it. It declares which elements it projects, which operations it may request, and which runtime or authority will settle the result.

### Transform

A **transform** is a reusable operation that produces one representation or structure from another. It may be built in, declarative, formula-based, lookup-based, scripted, plugin-provided, externally executed, or AI-assisted.

Every transform should declare:

- accepted inputs and produced outputs;
- deterministic or probabilistic behavior;
- loss characteristics;
- reversibility;
- dependencies and runtime;
- permissions and trust level;
- validation and error behavior;
- version and provenance.

### Workflow

A **workflow** coordinates controls, relations, transformations, approvals, jobs, and execution steps toward a goal. A migration, design review, configuration promotion, customer onboarding, or incident diagnostic can all be workflows.

### Run

A **run** is an attempted execution of a snapshot, transformation, mapping, synchronization, workflow, or validation plan. It produces a durable report containing inputs, versions, decisions, outputs, warnings, errors, approvals, timing, and provenance.

### Artifact

An **artifact** is a portable `.posh` document. It can describe systems, surfaces, mappings, transforms, workflows, policies, snapshots, libraries, or runs. Artifacts can import and layer other artifacts.

### Library

A **library** is a reusable package of artifacts and implementation materials. It may contain adapters, schemas, controls, surfaces, mappings, transforms, policies, workflows, examples, documentation, or runtime code.

## System scopes

PortaShape uses explicit scopes to prevent unlike values from being confused.

### Settings

**Settings** are global, structural, environmental, or system-level choices. They define how a system operates and the boundaries within which users work.

Examples include API endpoints, supported themes, global typography, feature availability, rendering mode, security policy, migration behavior, and system-wide accessibility constraints.

### Options

**Options** are user-, account-, audience-, session-, or use-case-focused choices. They describe a selected experience within the boundaries established by settings.

Examples include preferred theme, visible columns, selected dashboard modules, saved filters, language preference, display density, and motion intensity.

### Runtime state

**Runtime state** is the observed or active condition of a system: current application state, events, jobs, request status, component behavior, performance values, or provisional values.

Runtime state may be transient, but it remains important for diagnosis, tuning, preview, and provenance.

### Content

**Content** is authored or managed information such as pages, records, assets, metadata, translations, and relationships.

### Derived values

**Derived values** are calculated, inferred, aggregated, or generated from other values. Their provenance must identify contributing sources and transforms.

### Secrets and references

Sensitive credentials and secrets are never treated as portable ordinary values. A `.posh` artifact references secure connection profiles, secret identifiers, or runtime bindings managed outside the artifact.

## Authority and writer contracts

The included web-runtime material contributes two foundational rules that PortaShape generalizes beyond Alpine.js and htmx.

### One authoritative owner per value

Copies, drafts, projections, caches, and previews may exist, but one declared authority settles the meaningful value.

Typical authorities include:

- server or database for durable, shared, permission-sensitive truth;
- URL or route for navigable state;
- native control for a submitted proposal;
- runtime subsystem for current execution facts;
- user profile for personal options;
- policy engine for constraints;
- source repository for code-owned configuration.

PortaShape stores authority as model metadata and uses it to determine which edits are temporary, proposed, committed, synchronized, or invalid.

### One intentional writer per rendered or mutable boundary

Every significant DOM region, file region, record field, configuration scope, or system boundary should have one intended mutation mechanism at a time.

PortaShape records the writer or execution path so that generated controls, transformations, and synchronization do not create competing mutation authorities.

### Semantic contracts across boundaries

Independent owners communicate through explicit operations and events. Command events request work; fact events announce completed outcomes. Payload, scope, timing, failure behavior, and version must be documented.

This rule applies to browser events, API messages, workflow steps, runtime signals, and system-to-system synchronization.

## Mapping vocabulary

### Mapping

Mapping establishes intended correspondence.

```text
source.siteTitle → destination.projectName
```

The names or structures may differ, but the relationship states that the values play equivalent or coordinated roles.

### Translation

Translation changes representation while preserving intended meaning.

Examples include unit conversion, enum lookup, date formatting, path rewriting, color conversion, identifier resolution, and token-to-variable conversion.

### Transmutation

Transmutation creates a destination form through substantial restructuring or derivation. It covers one-to-many, many-to-one, many-to-many, inferred, generated, or reconstructed outcomes.

Examples include generating a typography scale, reconstructing a component from content plus styles plus behavior, or deriving a destination theme from brand constraints.

### Synchronization

Synchronization repeatedly applies a relationship over time. Direction, trigger, reversibility, conflict policy, and loss behavior must be explicit.

## Relationship patterns

PortaShape supports:

- one-to-one;
- one-to-many;
- many-to-one;
- many-to-many;
- conditional;
- lookup;
- formula;
- template;
- procedural;
- semantic;
- event-triggered;
- bidirectional where safely reversible.

## Value lifecycle

A value may move through these states:

```text
DISCOVERED → CLASSIFIED → EXPOSED → PROPOSED → PREVIEWED → VALIDATED
          → APPROVED → APPLIED → OBSERVED → RECORDED → COMPARED
```

Not every workflow uses every state, but the distinctions prevent temporary tuning from being confused with production changes.

## Provenance model

For any result, PortaShape should answer:

- which source elements contributed;
- which relation and transform versions were used;
- what was copied, inferred, generated, or manually overridden;
- whether information was lost;
- which policy and validation checks ran;
- who or what approved the change;
- when and where it was applied;
- whether the destination has since drifted.

## Unresolved values

An unresolved value is a first-class model object, not an omission. It includes the source, reason, severity, candidate resolutions, required decision, fallback, and whether execution can continue.

## The system graph as shared language

Different roles may view the same element differently:

- a developer sees a property, schema, event, or function;
- a designer sees a token, component state, motion parameter, or visual role;
- an operator sees a field, queue, action, or status;
- a product manager sees a feature parameter, experiment, workflow, or outcome;
- a migration specialist sees source meaning, destination capability, and transfer risk.

PortaShape keeps these views connected by stable element identities and relations rather than creating independent copies of the system.