# PortaShape Capabilities and Modules

## Engines, not isolated mini-products

PortaShape contains several capability engines, but they should not appear as unrelated applications. Each engine reads and writes the same system graph, participates in the same provenance model, and produces composable `.posh` artifacts.

## 1. Connect

**Purpose:** Establish safe, typed access to systems.

**Capabilities:**

- databases, APIs, files, spreadsheets, event streams, repositories, runtimes, content systems, design systems, analytics, and services;
- read-only, write, environment, field, and role permissions;
- adapter discovery and capability negotiation;
- version, schema, and connection metadata;
- secure credential references;
- local, hosted, embedded, and agent-mediated connections.

**Produces:** system declarations, capability manifests, permission boundaries, connection diagnostics.

## 2. Discover

**Purpose:** Turn heterogeneous materials into a common system model.

**Capabilities:**

- schema and type discovery;
- code, configuration, route, component, event, token, and content interpretation;
- runtime observation;
- semantic role classification;
- constraint and validation extraction;
- ownership, lifecycle, and scope inference;
- dependency and relationship discovery;
- confidence and evidence recording;
- user annotations and corrections.

**Produces:** typed elements, relations, observations, suggested controls, suggested mappings.

## 3. Surface

**Purpose:** Generate useful interfaces from the system model.

**Capabilities:**

- type-to-control mapping;
- tables, filters, editors, inspectors, dashboards, graphs, timelines, previews, and workflow surfaces;
- automatic, guided, manual, and adaptive composition;
- permission-aware control generation;
- role-sensitive views over one model;
- accessible interaction patterns;
- reusable surface components and layouts;
- embedding into existing products or operating as a standalone workspace.

**Produces:** surface artifacts, saved views, control groups, role-specific compositions.

## 4. Runtime

**Purpose:** Observe and shape a connected system while it is operating.

**Capabilities:**

- live values, events, requests, jobs, component behavior, network activity, and performance signals;
- immediate temporary overrides;
- pause, replay, scenario simulation, and edge-case injection where supported;
- design-token and motion tuning;
- comparison of runtime configurations;
- promotion of accepted adjustments into source patches or configuration;
- capture of presets and runtime snapshots.

**Produces:** observations, proposed changes, presets, patches, snapshots, traces.

## 5. Relate

**Purpose:** Define how elements correspond within or across systems.

**Capabilities:**

- direct, one-to-many, many-to-one, many-to-many, conditional, lookup, formula, template, procedural, and semantic relations;
- drag-and-drop, keyboard, bulk, declarative, and suggested mapping;
- confidence and explanation;
- direction, priority, conflict, and synchronization policy;
- layered mappings from platform to organization to project to environment to user.

**Produces:** mapping and synchronization artifacts.

## 6. Transform

**Purpose:** Translate or transmute values and structures.

**Capabilities:**

- built-in conversions;
- visual formulas and lookup tables;
- template composition;
- scripts, plugins, external APIs, and sandboxed procedures;
- AI-assisted generation of structured transformations;
- code, token, asset, content, schema, and component generation;
- reversibility and loss analysis;
- reusable transform pipelines.

**Produces:** transform artifacts, generated values, conversion traces, loss metadata.

## 7. Verify

**Purpose:** Establish confidence before and after change.

**Capabilities:**

- type, range, format, schema, referential integrity, capability, permission, accessibility, brand, performance, and visual checks;
- assertions and policy evaluation;
- dry runs and simulation;
- unresolved value management;
- overwritten and downstream-effect analysis;
- source, transformed, and destination comparison;
- visual and behavioral regression support;
- compatibility and version checks.

**Produces:** validation reports, policy results, unresolved objects, risk summaries.

## 8. Run

**Purpose:** Execute controlled system change.

**Capabilities:**

- snapshots, patches, exports, imports, migrations, synchronization, reconstruction, generation, and workflow execution;
- one-time, manual, scheduled, event-driven, continuous, source-to-destination, destination-to-source, bidirectional, and preview-only modes;
- job state, retry, cancellation, idempotency, and partial rerun;
- approval gates and environment promotion;
- conflict-resolution strategies;
- rollback and compensation where supported.

**Produces:** run reports, changed systems, generated output, audit events, rollback points.

## 9. Compare

**Purpose:** Explain difference and drift.

**Capabilities:**

- snapshots across time;
- environments, branches, deployments, users, and systems;
- settings versus options;
- schema, token, component, content, route, permission, behavior, and runtime differences;
- mapping and transform version differences;
- migration inconsistency and destination drift;
- selective merge, transfer, approval, or rejection.

**Produces:** diffs, merge plans, drift alerts, updated mappings.

## 10. Preserve

**Purpose:** Retain reusable system knowledge.

**Capabilities:**

- `.posh` parsing, validation, writing, canonical formatting, and versioning;
- snapshots, surfaces, mappings, transforms, workflows, policies, libraries, and run reports;
- composition, imports, inheritance, overrides, namespaces, and signatures;
- human-readable notes and machine-readable semantics;
- source control integration and reviewable diffs.

**Produces:** portable artifacts and versioned system history.

## 11. Learn

**Purpose:** Convert repeated work into better abstractions.

**Capabilities:**

- identify frequently adjusted values;
- detect recurring mappings and transformation chains;
- recognize common unresolved destinations;
- suggest control groups, presets, workflows, policies, templates, and semantic concepts;
- analyze correlations, anomalies, and operational patterns;
- generate candidate rules with confidence and evidence;
- retain human acceptance or rejection as library knowledge.

**Produces:** suggestions, reusable abstractions, pattern reports, library contributions.

## 12. Library

**Purpose:** Share proven ways to connect, understand, control, and move systems.

A PortaShape library may include:

- adapters and connection profiles;
- schemas and semantic vocabularies;
- controls and surfaces;
- mapping packs;
- transformation functions;
- policies and validators;
- workflows and operational playbooks;
- implementation code;
- examples, tutorials, onboarding, and architecture guidance.

The included **PortaShape Web-Native Runtime Library** is the first example. It supplies patterns and education for building web control surfaces with server-rendered HTML, Alpine.js, htmx, native controls, semantic events, and explicit ownership boundaries.

## Cross-engine invariants

Every engine must preserve these invariants:

- stable element identity;
- explicit scope and authority;
- permission and sensitivity metadata;
- provenance and version context;
- visible uncertainty, loss, and unresolved state;
- artifact compatibility;
- common selection and inspection across lenses;
- safe separation between preview and execution.