# Product Concept: PortaShape — A Data Mapping, Translation, and Transmutation System

## Overview

PortaShape is a data mapping, translation, and transmutation utility designed to work alongside the runtime interface for building, tuning, and understanding digital systems.

Where the runtime interface exposes the internal structure and behavior of a system as an interactive control surface, PortaShape provides a structured way to move, reinterpret, transform, and preserve the values represented by that interface.

Together, the two systems create a shared environment for understanding both the state of a digital system and the relationships required to move that state somewhere else.

The runtime interface answers questions such as:

* What values exist in this system?
* Which values can be inspected or changed?
* How are these values grouped?
* Which values affect one another?
* What is the system doing right now?
* Which controls should be available to the user?

PortaShape answers a different but closely related set of questions:

* Where should each value go?
* What does this value mean in the destination system?
* Does the value need to be renamed, reformatted, translated, combined, split, or calculated?
* Which destination field is equivalent to this source field?
* Which parts of the source system should be preserved?
* Which values should be ignored, replaced, inferred, or generated?
* How can the complete mapping be saved, reused, inspected, versioned, and shared?

At its simplest, PortaShape allows a user to drag a source data point onto a destination data point and define the relationship between them.

At a more advanced level, it becomes a general-purpose system for translating one digital structure into another.

A completed mapping is saved as a structured JSON-based PortaShape file using the `.posh` extension.

This file describes the source structure, destination structure, relationships between values, transformation rules, validation requirements, system settings, user options, and any additional information required to reproduce the translation.

## Core Idea

Digital systems frequently contain equivalent information expressed through different names, formats, structures, assumptions, and conventions.

One website may store its primary background color as:

`theme.colors.background`

Another may use:

`appearance.canvas.default`

A third may represent the same concept as a CSS custom property:

`--page-background`

The underlying intent may be identical, but the systems do not know that these values correspond to one another.

The same problem occurs across databases, content management systems, APIs, design systems, configuration files, component libraries, animation systems, user profiles, application settings, and entire websites.

PortaShape provides an interface for explicitly defining those relationships.

The user can inspect two or more systems through the shared runtime interface, select values from each system, and visually connect them.

Each connection becomes a mapping rule.

The mapping rule can be direct, transformed, conditional, calculated, combined with other values, or resolved through a custom process.

Once the mapping is complete, PortaShape saves the configuration as a `.posh` file. That file acts as a portable description of how one system can be translated into another.

## Why PortaShape Works with the Runtime Interface

The runtime interface and PortaShape should share the same controls, inspectors, visualizations, data adapters, and system vocabulary.

This is important because data mapping should not happen in an isolated utility that understands less about the connected systems than the interface used to operate them.

The runtime interface already exposes:

* Available values
* Data types
* Constraints
* Relationships
* Default values
* Current runtime values
* Component properties
* CSS rules
* Design tokens
* Configuration values
* Content structures
* Animation parameters
* Validation rules
* User-adjustable controls
* System-generated observations

PortaShape can use that same information to make mappings more accurate and understandable.

For example, the runtime interface may already know that a field represents a color, a duration, an enum, a database identifier, a content reference, a font family, or a user preference.

PortaShape can use this metadata when suggesting destination values and transformation rules.

The same slider used to tune an animation duration can be used to preview how a mapped duration will behave in the destination system.

The same color control used to edit a design token can show how a source color is being converted into a destination color format.

The same table used to inspect database records can show source values beside transformed destination values.

The two products therefore operate as parts of a larger system:

1. The runtime interface discovers and exposes a system.
2. PortaShape establishes how that system relates to another system.
3. The runtime interface previews and tunes the result.
4. PortaShape records the relationship in a portable configuration.
5. The mapping can then be run repeatedly, reversed where possible, audited, tested, and reused.

## Mapping, Translation, and Transmutation

PortaShape supports three related but distinct operations.

### Mapping

Mapping defines a relationship between a source value and a destination value.

A direct mapping may say:

`source.siteTitle → destination.projectName`

The source and destination values may have different names but represent the same concept.

Mapping establishes equivalence or intended correspondence.

### Translation

Translation changes how a value is expressed while preserving its intended meaning.

Examples include:

* Converting a hexadecimal color into RGB
* Converting pixels into rem units
* Translating a source enum into a destination enum
* Renaming a property
* Reformatting a date
* Converting a string into a boolean
* Resolving an identifier into a referenced object
* Translating one content schema into another
* Converting a design token into a CSS variable
* Rewriting a path or URL for a new environment

Translation preserves the conceptual value while changing its representation.

### Transmutation

Transmutation creates a destination value through a more substantial transformation.

The destination value may not have a one-to-one equivalent in the source.

Examples include:

* Combining multiple source fields into one destination field
* Splitting one source field into several destination values
* Calculating a spacing scale from a base unit
* Generating a responsive typography system from a small set of source values
* Deriving a destination theme from brand guidelines
* Converting a collection of CSS rules into structured design tokens
* Converting a component’s runtime behavior into reusable configuration
* Creating animation presets from recorded motion values
* Inferring a destination value from several related source signals
* Reconstructing a destination component from content, styles, and behavior

Transmutation allows PortaShape to operate beyond basic import and export.

It becomes a structured conversion engine capable of producing new forms while preserving the source system’s intent.

## Visual Mapping Interface

The central PortaShape experience is a visual mapping workspace.

The workspace may present source values on one side and destination values on the other.

These values may be shown as:

* Fields
* Nodes
* Cards
* Tree structures
* Tables
* Component properties
* Controls
* Tokens
* CSS declarations
* Data records
* Schema definitions
* Runtime events
* Content blocks
* File structures

The user can drag a source value and drop it onto a destination value.

A visible connection is created between them.

The connection can then be configured through a mapping inspector.

The mapping inspector may allow the user to define:

* Relationship type
* Transformation function
* Input and output types
* Default behavior
* Fallback values
* Validation rules
* Conditions
* Priority
* Direction
* Synchronization behavior
* Conflict resolution
* Error handling
* Human-readable notes
* Confidence level
* Approval status

The system should also support mapping through direct selection, keyboard workflows, search, bulk actions, automated suggestions, and code-based definitions.

Drag and drop is the most intuitive interaction, but it should not be the only interaction.

## Mapping Relationship Types

PortaShape should support multiple relationship patterns.

### One-to-One Mapping

One source value maps directly to one destination value.

Example:

`source.theme.primaryColor → destination.brand.colorPrimary`

### One-to-Many Mapping

One source value produces several destination values.

Example:

A source brand color may populate:

* Button background
* Link color
* Focus ring color
* Active navigation color

### Many-to-One Mapping

Several source values combine into one destination value.

Example:

`firstName + lastName → displayName`

### Many-to-Many Mapping

A set of source values is transformed into a new destination structure.

Example:

A source typography system may be converted into a destination type scale with different naming, sizing, line-height, and breakpoint rules.

### Conditional Mapping

A value maps differently depending on one or more conditions.

Example:

* If `themeMode` is dark, use one destination palette.
* If the user role is administrator, map additional permissions.
* If a source component has an image, generate an image-based destination variant.
* If a value is absent, use a fallback.

### Lookup Mapping

A source value is resolved through a lookup table.

Example:

`"large" → "lg"`

`"centered" → "align-center"`

`source category ID → destination category ID`

### Formula Mapping

The destination value is calculated.

Example:

`destination.lineHeight = source.fontSize × 1.5`

### Template Mapping

A destination value is created from a template.

Example:

`"/assets/{source.filename}"`

### Procedural Mapping

A custom function or external process generates the destination value.

This may be useful for complex conversions, asset processing, code generation, or AI-assisted transformations.

### Semantic Mapping

The mapping is based on meaning rather than exact structure.

For example, a source value called `accent` may be mapped to `interactive-primary` because both describe the same functional role, even though their names differ.

## Automatic Mapping Assistance

PortaShape should assist users by suggesting likely mappings.

The system can compare source and destination values using:

* Field names
* Descriptions
* Data types
* Value ranges
* Default values
* Runtime usage
* Parent and child relationships
* Semantic meaning
* Existing mapping libraries
* Code references
* CSS selectors
* Design-token roles
* User behavior
* Historical mapping decisions
* Brand-language similarity

Suggestions should be presented with a confidence level and an explanation.

For example:

> Suggested mapping: `source.primaryColor` to `destination.brand.actionColor`

> Reason: Both fields are color values used by primary interactive controls.

The user can accept, reject, modify, or replace the suggestion.

The objective is not to remove the user from the mapping process. The objective is to reduce repetitive work while keeping the mapping understandable and controllable.

## PortaShape Files

A PortaShape mapping is saved as a JSON-structured file using the `.posh` extension.

The `.posh` file is intended to be human-readable, machine-readable, portable, versionable, and extensible.

It acts as a formal description of how source systems relate to destination systems.

A `.posh` file may contain:

* File-format version
* PortaShape specification version
* Mapping name
* Description
* Authors
* Creation and modification dates
* Source definitions
* Destination definitions
* Schema references
* Source value paths
* Destination value paths
* Data types
* Mapping relationships
* Translation rules
* Transmutation rules
* Validation constraints
* Defaults
* Fallbacks
* Conditions
* Lookup tables
* Execution order
* Dependencies
* Settings
* Options
* Runtime observations
* Migration history
* Compatibility information
* Permissions
* Audit metadata
* Extension namespaces

The complete `.posh` specification and its key/value schemas should be developed as a separate technical standard after the core concept has been established.

That standard should define which keys are required, which are optional, how values are typed, how mappings are executed, and how third-party extensions are introduced without breaking compatibility.

## Conceptual `.posh` Structure

The following is an illustrative structure rather than a finalized specification:

```json
{
  "portaShape": {
    "formatVersion": "0.1",
    "name": "Source Website to Destination Website",
    "description": "Maps the source website configuration into the destination platform.",
    "source": {
      "type": "website",
      "adapter": "source-platform-adapter",
      "schema": "source-schema-reference"
    },
    "destination": {
      "type": "website",
      "adapter": "destination-platform-adapter",
      "schema": "destination-schema-reference"
    },
    "mappings": [
      {
        "id": "mapping-primary-color",
        "source": "theme.colors.primary",
        "destination": "brand.actionColor",
        "operation": "translate",
        "transform": "color.hexToRgb"
      }
    ],
    "settings": {},
    "options": {},
    "validation": {},
    "metadata": {}
  }
}
```

This example shows the general intention but does not define the final standard.

The eventual specification should support both simple mappings and large, multi-stage transformation systems.

## Settings and Options as First-Class PortaShape Vocabulary

PortaShape introduces two first-class vocabulary terms: **settings** and **options**.

These terms should have distinct meanings throughout the interface, file specification, documentation, and execution model.

### Settings

Settings are primarily global, structural, environmental, or system-related choices.

They influence how the system operates as a whole.

Examples include:

* Site-wide theme configuration
* Database connection behavior
* Build environment
* API endpoints
* Localization defaults
* Global typography
* Default spacing scale
* Security policies
* Feature flags
* Rendering mode
* Cache behavior
* Global animation preferences
* Content-delivery configuration
* System-wide accessibility rules
* Migration behavior
* Mapping execution mode

Settings generally describe the system or environment.

They may apply to every user, every page, every component, or an entire deployment.

They often require elevated permissions because changing them may affect many people or alter the behavior of the complete system.

### Options

Options are primarily user-focused choices, preferences, selections, or variations.

They influence how an individual user, account, audience, session, or use case experiences the system.

Examples include:

* A user’s preferred theme
* Dashboard layout
* Visible columns
* Notification preferences
* Language preference
* Saved filters
* Display density
* Preferred animation intensity
* Selected component variant
* Personal accessibility preferences
* Default sorting behavior
* User-specific content controls
* Workspace preferences
* Per-account presentation choices

Options generally describe a user’s chosen experience within the system.

They may override or operate within boundaries established by settings.

### Relationship Between Settings and Options

Settings define the system’s available structure and boundaries.

Options allow users to make choices within that structure.

For example:

* A setting may define which themes are available.

* An option records which theme a user selected.

* A setting may define the supported languages.

* An option records the user’s preferred language.

* A setting may establish the allowable animation range.

* An option records the user’s preferred motion intensity.

* A setting may define the available dashboard modules.

* An option records which modules a user has chosen to display.

This distinction should remain explicit in `.posh` files so that PortaShape can correctly determine whether a value is global, environmental, account-level, session-level, or user-specific.

## Website Transfer and Reconstruction

One of the most significant PortaShape use cases is transferring a website from one platform or implementation to another.

A website is not only a collection of pages and assets.

It is a connected system of:

* Content
* Styles
* Design tokens
* Layout rules
* Components
* Routes
* Navigation
* Metadata
* Assets
* User preferences
* Global settings
* Feature configuration
* Interactions
* Animations
* Forms
* Integrations
* Permissions
* Runtime behavior

Traditional migration tools often move only part of this system.

They may migrate content without preserving design behavior, transfer data without translating configuration, or copy static HTML without capturing the underlying system.

PortaShape aims to transfer a website value for value wherever a meaningful equivalent can be established.

The process may include:

1. Connecting to the source website.
2. Inspecting its data, code, styles, configuration, and runtime behavior.
3. Connecting to the destination environment.
4. Discovering the destination schema and available capabilities.
5. Matching equivalent values.
6. Translating incompatible formats.
7. Transmuting structures where direct equivalents do not exist.
8. Previewing the destination result.
9. Identifying unsupported or unresolved values.
10. Saving the complete relationship as a `.posh` file.
11. Running the transfer.
12. Validating the migrated website.
13. Recording the migration results and any manual decisions.

The migration can be repeated, updated, or partially rerun when either system changes.

## Value-for-Value Transfer

The phrase “value for value” describes the effort to preserve the meaningful state of the source system rather than merely copying its surface output.

A value-for-value transfer attempts to identify every relevant source value and determine how it should exist in the destination.

This includes visible values, such as colors and text, as well as less visible values, such as:

* Breakpoints
* Accessibility rules
* Permission levels
* Content relationships
* Animation timing
* Form behavior
* Metadata
* Defaults
* Feature flags
* User preferences
* Validation behavior
* Component states
* Fallback logic
* Routing rules
* System options
* Global settings

Some values can be transferred directly.

Some must be translated.

Some require transmutation.

Some may not have a destination equivalent and must be marked as unresolved.

PortaShape should make each of these outcomes visible.

The system should avoid pretending that a migration is complete when important values were discarded or approximated.

## Website Settings Snapshot

PortaShape can also capture a website’s current state without immediately transferring it.

This produces a structured snapshot of the site’s settings and options at a particular moment.

A snapshot could include:

* Global configuration
* Theme values
* Design tokens
* Plugin configuration
* User preferences
* Active feature flags
* Content-system settings
* Animation parameters
* Navigation structure
* Layout choices
* Component defaults
* Localization choices
* Accessibility configuration
* Integration settings
* Environment-specific values

The snapshot is saved as a `.posh` file.

This file can function as:

* A backup
* A versioned configuration record
* A deployment baseline
* A migration source
* A comparison target
* A reproducible environment definition
* A diagnostic artifact
* A design-system snapshot
* A customer configuration package
* A rollback point

Because settings and options are stored separately, a snapshot can distinguish between the state of the website itself and the preferences of its users.

## Snapshot Comparison

Two `.posh` snapshots can be compared to identify changes over time.

The comparison may reveal:

* Added values
* Removed values
* Modified values
* Changed data types
* New settings
* Changed options
* Schema drift
* Missing dependencies
* Design-token changes
* Feature-flag changes
* User-preference changes
* Environment differences
* Migration inconsistencies
* Runtime deviations

The runtime interface can display these differences visually.

A user may approve, reject, merge, or selectively transfer individual changes.

This makes PortaShape useful not only for migration but also for configuration management and system auditing.

## Live Synchronization

PortaShape may support ongoing synchronization between systems.

A `.posh` file could define whether each mapping is:

* One-time
* Manually triggered
* Scheduled
* Event-driven
* Continuously synchronized
* Source-to-destination only
* Destination-to-source only
* Bidirectional
* Preview-only

For bidirectional mappings, the system must define how conflicts are resolved.

Possible strategies include:

* Source always wins
* Destination always wins
* Most recent value wins
* Higher-priority system wins
* Require human approval
* Merge values
* Run a custom conflict-resolution function

The interface should clearly show when a mapping is reversible and when a transformation loses information.

A lossy transformation should never be represented as safely reversible.

## Preview and Simulation

Before applying a PortaShape mapping, users should be able to preview its effects.

The preview may show:

* Original source value
* Transformed value
* Destination value
* Validation result
* Warnings
* Errors
* Unresolved mappings
* Overwritten values
* Generated values
* Unsupported values
* Changes to settings
* Changes to options
* Downstream effects

The user should be able to simulate a complete transfer without writing to the destination.

A simulation can generate a report describing what would happen.

This allows migrations and large transformations to be reviewed before they become destructive.

## Validation and Testing

PortaShape should treat validation as a core part of the mapping process.

A mapping is not successful merely because a destination value was written.

The destination value must also be valid and preserve the intended meaning.

Validation may include:

* Type checks
* Required-value checks
* Range checks
* Format checks
* Schema validation
* Referential-integrity checks
* Asset-existence checks
* Accessibility checks
* Brand-rule checks
* Visual-regression checks
* Runtime-behavior checks
* Content-completeness checks
* Permission checks
* Destination-capability checks

The system may also allow users to define assertions.

For example:

* Every published page must have a title.
* Every source route must have a destination route.
* Every source color token must be mapped.
* No global setting may be silently discarded.
* User options must remain scoped to the correct user.
* Destination animations must remain within performance limits.

Validation results should be stored with the mapping or execution report.

## Mapping Levels

PortaShape may operate at several levels of abstraction.

### Raw Data Level

Maps individual values, fields, records, and properties.

### Schema Level

Maps structural definitions such as database schemas, content models, configuration formats, or API objects.

### Component Level

Maps components, their properties, states, styles, events, and children.

### Design-System Level

Maps colors, typography, spacing, layout, motion, tokens, patterns, and component variants.

### Application Level

Maps routes, features, permissions, configuration, user preferences, integrations, and runtime behavior.

### Website Level

Maps the complete website as a coordinated system.

The same `.posh` format should support all of these levels through consistent primitives and extensible schemas.

## Reusable Mapping Libraries

Mappings should be reusable.

A user may create a library that describes how one platform commonly maps to another.

Examples include:

* CMS A to CMS B
* Design-token format A to format B
* CSS variables to a component theme
* Database schema A to schema B
* Animation library A to animation library B
* E-commerce platform A to platform B
* User-preference model A to model B

A reusable library can provide default mappings that are then customized for a specific project.

PortaShape may support layered mapping files:

1. A base platform mapping
2. An organization-specific mapping
3. A project-specific mapping
4. An environment-specific override
5. A user-specific options layer

This allows broad standards to coexist with local customization.

## Manual and Generated Transformations

Transformations may be defined through several methods:

* Built-in operations
* Visual formulas
* Lookup tables
* User-written functions
* Scripts
* Plugins
* External APIs
* AI-assisted procedures
* Reusable mapping components
* Declarative transformation blocks

Every transformation should be inspectable.

A user should be able to understand why a destination value was produced and which source values contributed to it.

This is especially important when AI is used.

AI may suggest mappings or generate transformation logic, but the resulting rule should be represented in a structured, reviewable form wherever possible.

## Provenance and Traceability

PortaShape should preserve provenance.

For every destination value, the system should be able to answer:

* Which source value produced this?
* Which mapping rule was used?
* Which transformations were applied?
* Which version of the `.posh` file was used?
* When was the value transferred?
* Who approved the mapping?
* Was the value generated or copied?
* Was the transformation lossy?
* Were any warnings produced?
* Has the destination value changed since transfer?

This information can be presented through the runtime interface as a trace or history.

Provenance makes migrations easier to debug and allows users to understand the origin of generated systems.

## Security and Permissions

Because PortaShape may read from and write to production systems, security must be fundamental.

The system should support:

* Read-only connections
* Write permissions
* Field-level permissions
* Environment restrictions
* User-role restrictions
* Approval workflows
* Secret management
* Credential isolation
* Audit logs
* Signed mapping files
* Trusted and untrusted transformations
* Sandboxed execution
* Change previews
* Rollback support

A `.posh` file should not need to contain raw secrets.

It should reference secure credentials or connection profiles managed separately.

The specification should clearly distinguish between portable configuration and sensitive runtime information.

## Versioning and Compatibility

The `.posh` standard should be versioned.

A file should identify:

* File-format version
* Schema version
* Required features
* Optional extensions
* Adapter versions
* Source-system version
* Destination-system version
* Transformation-runtime version

PortaShape should detect incompatible mappings before execution.

When a connected system changes, the interface should identify which mappings may be affected.

This allows the user to update the mapping rather than discovering incompatibility only after a failed transfer.

## Error Handling and Unresolved Values

Not every source value will have a valid destination.

PortaShape should treat unresolved values as explicit objects rather than silently dropping them.

An unresolved mapping may include:

* Source path
* Source value
* Reason it could not be mapped
* Suggested destinations
* Required user decision
* Severity
* Whether transfer can continue
* Possible fallback
* Supporting context

The user can return to unresolved values and address them manually.

This is especially important for full website migrations, where missing values may affect visual fidelity, functionality, accessibility, or content integrity.

## Relationship to the Runtime Control Surface

After a mapping is created, it can become part of the runtime interface.

Each mapped relationship may be represented as a control, status indicator, or visualization.

A user may:

* Change a source value and see the destination preview update
* Tune the transformation function in real time
* Compare source and destination rendering
* Pause synchronization
* Override a mapped value
* Inspect mapping history
* View unresolved relationships
* Turn a manual adjustment into a saved mapping rule
* Create higher-level controls from groups of mappings
* Analyze recurring mapping failures
* Detect values that frequently require manual intervention

The runtime interface therefore becomes the operational surface for PortaShape.

PortaShape provides the data relationships, while the runtime interface provides the interaction model.

## Pattern Discovery

Because PortaShape observes mappings across systems, it can identify recurring patterns.

It may discover that:

* Certain source fields are consistently mapped together
* A particular platform uses different names for the same concepts
* Some transformations recur across many projects
* Certain destination fields frequently lack equivalents
* User settings are often mistaken for user options
* Specific migrations repeatedly require manual correction
* A common group of mappings should become a reusable template
* A higher-level semantic concept can replace many low-level mappings

These patterns can generate new mapping suggestions, transformation utilities, adapters, controls, or reusable PortaShape modules.

As with the runtime interface, the system becomes more useful as it learns which abstractions users repeatedly need.

## Potential Use Cases

### Website Migration

Transfer content, styles, components, configuration, settings, options, and runtime behavior from one website platform to another.

### Website Cloning Across Environments

Reproduce a website’s configuration in development, staging, testing, or production.

### Configuration Backup

Capture a structured snapshot of system settings and user options.

### Design-System Translation

Convert one token system, component library, or theme format into another.

### CMS Migration

Map content types, fields, references, assets, routes, and publishing states between content systems.

### Application Modernization

Translate configuration and behavior from a legacy application into a new architecture.

### Customer Onboarding

Import a customer’s existing data and preferences into a product-specific structure.

### Multi-Platform Publishing

Map one structured content source into several destinations with different requirements.

### Data Integration

Connect APIs, databases, files, and services through understandable visual mappings.

### User Preference Portability

Move user-focused options between compatible products or environments.

### Brand-System Conversion

Translate brand rules into design tokens, component themes, content constraints, and motion guidelines.

### Animation-System Translation

Convert timing, easing, keyframes, events, and motion parameters between animation frameworks.

## Key Product Principles

### Meaning Before Format

PortaShape should attempt to preserve what a value means, not only how it is currently represented.

### Visible Relationships

Mappings and transformations should be inspectable through a clear visual interface.

### Explicit Loss

When a conversion loses information, the system should state this clearly.

### Reusability

Mappings should be saved, shared, layered, extended, and applied repeatedly.

### Human Control

Automatic suggestions should accelerate work without hiding important decisions.

### Shared Interfaces

PortaShape and the runtime system should use the same inspectors, controls, previews, and component vocabulary.

### Traceability

Every generated destination value should be traceable to its source and transformation history.

### Safe Execution

Preview, validation, permissions, audit history, and rollback should be foundational.

### Extensible Standards

The `.posh` format should support extensions without becoming dependent on one platform or implementation.

## Possible System Architecture

PortaShape may be organized into several layers.

### Source and Destination Adapters

Connectors that read and write values from websites, databases, APIs, files, codebases, design systems, and runtime environments.

### Schema Discovery Layer

A system for identifying available fields, data types, relationships, constraints, settings, options, and capabilities.

### Mapping Layer

The structure that defines relationships between source and destination values.

### Transformation Layer

The runtime that performs translation and transmutation operations.

### Visual Composition Layer

The interface where users drag, drop, connect, inspect, group, and edit mappings.

### Validation Layer

The system that checks values before and after transfer.

### Execution Layer

The engine that performs snapshots, migrations, synchronization, and transformations.

### Provenance Layer

The system that records the origin and history of every mapped value.

### PortaShape File Layer

The parser, validator, writer, and version manager for `.posh` files.

### Runtime Interface Layer

The shared controls and visualizations used to preview, tune, and understand the system.

## High-Level `.posh` Specification Work to Follow

The next phase should define a formal high-level specification for the PortaShape file standard.

That specification should establish:

* The root file structure
* Required and optional keys
* Naming conventions
* Data typing rules
* Source and destination declarations
* Mapping identifiers
* Mapping direction
* Operation types
* Translation definitions
* Transmutation definitions
* Conditions
* Lookup tables
* Settings schema
* Options schema
* Validation schema
* Error representation
* Unresolved-value representation
* Execution metadata
* Provenance metadata
* Security boundaries
* Extension mechanisms
* Versioning rules
* Compatibility rules
* Serialization requirements
* Canonical formatting
* Digital-signature support
* Partial-file composition
* Inheritance and overrides
* Layered mapping behavior

The specification should remain small enough for simple use cases while being extensible enough to represent complete website migrations and complex system transformations.

## Long-Term Vision

The long-term vision is for PortaShape to become a portable language for describing how digital systems correspond to one another.

Today, migrations and integrations are often implemented as one-off scripts, manual spreadsheets, undocumented decisions, or platform-specific import tools.

Those approaches may accomplish the immediate transfer, but they rarely preserve a clear, reusable explanation of what was mapped, why it was mapped, and how the result was produced.

PortaShape turns that explanation into a structured artifact.

A `.posh` file can become:

* A migration plan
* A transformation program
* A system snapshot
* A compatibility contract
* A configuration package
* A synchronization definition
* A reusable mapping library
* A record of architectural decisions
* A portable description of system state

When combined with the runtime interface, PortaShape allows users to see a digital system, operate it, map it, transform it, move it, and reconstruct it through the same family of interfaces.

The runtime interface makes systems visible and controllable.

PortaShape makes systems portable and translatable.

Together, they provide a foundation for moving digital products between platforms without reducing them to static files or disconnected data.

They create a system for preserving not only what a product contains, but also how its values relate, how its choices are scoped, and how its behavior can be reproduced elsewhere.

## Concise Positioning Statement

PortaShape is a visual data mapping, translation, and transmutation utility that connects source values to destination values through a shared runtime interface.

Users can drag and drop data points, define direct or transformed relationships, distinguish global system settings from user-focused options, preview the results, and save the complete mapping as a structured `.posh` file.

Used with the runtime interface, PortaShape can capture the current state of a website, translate that state into another system, and transfer the site value for value wherever meaningful equivalents can be established.