# PortaShape Governance, Security, and Validation

## Governance is part of shaping

PortaShape may inspect and change production systems, generate code, move user data, alter global settings, execute transformations, and synchronize environments. Safety cannot be a final confirmation dialog attached to an otherwise opaque process. Authority, permission, validation, trust, and provenance belong in the system model from the beginning.

## Authority model

Every mutable element declares:

- the authoritative system or subsystem;
- allowed readers and writers;
- whether a surface can observe, propose, preview, commit, or invoke;
- environment restrictions;
- field or scope restrictions;
- whether approval is required;
- conflict and settlement behavior;
- audit sensitivity.

A responsive preview is not automatically authoritative. A disabled control is not authorization. An AI suggestion is not approval.

## Permission model

PortaShape should support:

- read-only connections;
- write and command permissions;
- field-level and element-level permissions;
- role and user restrictions;
- environment restrictions;
- separate permission for settings and options;
- approval workflows;
- temporary elevated access;
- scoped service identities;
- audit of human and agent actions.

Generated surfaces hide or disable unavailable operations, but enforcement remains at the adapter and authoritative system.

## Secret handling

Portable artifacts should not require raw secrets. They reference:

- connection profile IDs;
- environment bindings;
- secret-manager paths;
- credential capabilities;
- runtime-provided tokens.

Artifacts remain safe to inspect and version without executing or resolving secrets.

## Trust and execution

Transforms and extensions declare a trust class, for example:

- pure built-in operation;
- reviewed declarative transform;
- signed plugin;
- sandboxed user code;
- external service;
- AI-assisted procedure;
- untrusted imported logic.

The run planner can require stronger review, isolation, or deny execution based on trust, destination, and data sensitivity.

## Preview and dry run

Before material change, PortaShape should be able to present:

- original source value;
- proposed or transformed value;
- current destination value;
- overwritten values;
- dependent elements and downstream effects;
- settings and options changes;
- validation results;
- unresolved mappings;
- unsupported capabilities;
- generated values;
- loss and reversibility;
- required approvals;
- expected writes and commands.

A dry run produces a report that can be reviewed and signed without changing the destination.

## Validation layers

### Artifact validation

Check format version, required fields, references, typing, imports, extension schemas, signatures, and canonical serialization.

### Connection validation

Check adapter compatibility, permissions, environment, schema version, and required capabilities.

### Value validation

Check type, range, format, required fields, allowed values, and normalization.

### Relationship validation

Check mapping completeness, transform compatibility, dependency cycles, direction, reversibility, and conflict policy.

### Domain validation

Check referential integrity, asset existence, content completeness, route coverage, permission scope, brand rules, accessibility, performance, and business assertions.

### Post-execution validation

Observe destination state, behavior, visual output, jobs, and drift after the write settles.

## Assertions

Examples of portable assertions include:

- every published page has a title;
- every source route has a destination route;
- every source color role is mapped;
- no global setting is silently discarded;
- user options remain scoped to the correct user;
- destination motion remains within performance and accessibility limits;
- every generated value has provenance;
- no unapproved transform writes to production.

## Explicit loss

A transform declares whether it is:

- lossless and reversible;
- lossless but not automatically reversible;
- lossy with known discarded information;
- approximate;
- inferred with confidence;
- non-deterministic;
- unresolved.

The UI must never portray a lossy relation as safely bidirectional.

## Unresolved values

Unresolved values include:

- source element and value;
- intended destination context;
- reason;
- severity;
- candidate mappings or fallbacks;
- required human decision;
- continuation policy;
- effect on fidelity, functionality, accessibility, content, or security.

A run can pause, skip, use a fallback, or continue with explicit approval according to policy.

## Conflict handling

Synchronization and multi-writer workflows require a declared strategy:

- source wins;
- destination wins;
- most recent wins;
- priority system wins;
- merge;
- custom resolver;
- human approval.

PortaShape should show the authority assumptions and information loss of the chosen strategy.

## Audit and provenance

Audit records capture:

- actor identity, including agents and automation;
- operation and affected elements;
- source and destination systems;
- artifact, adapter, transform, and policy versions;
- approvals;
- before and after values where permitted;
- warnings, errors, and unresolved values;
- execution timing and environment;
- rollback or compensation action;
- later destination drift.

## Rollback and recovery

Rollback support may use:

- pre-run snapshots;
- inverse transforms where verified;
- source-control reversion;
- destination-native transactions;
- compensating workflows;
- item-level rerun;
- manual recovery instructions.

PortaShape must distinguish guaranteed rollback from best-effort compensation.

## Web surface safety

The Web-Native Runtime Library contributes implementation requirements for generated surfaces:

- server-side authentication, authorization, validation, CSRF enforcement, sanitization, transaction integrity, and audit;
- native accessible controls and labels;
- deliberate focus after swaps, errors, overlays, and navigation;
- semantic status announcements;
- strict boundaries for untrusted HTML;
- cleanup for timers, observers, listeners, and rich widgets;
- direct URL and normal form/link behavior where progressive enhancement is promised;
- version-aware htmx lifecycle and error handling;
- testing of full pages, fragments, races, history, accessibility, and lifecycle.

## AI governance

AI may assist with discovery, semantic classification, mapping suggestions, transform generation, documentation, and anomaly detection. PortaShape should record:

- model or service identity and version where available;
- input scope and protected data policy;
- prompt or procedure identity;
- confidence and evidence;
- generated structured rule;
- human review and modifications;
- deterministic validation applied afterward.

AI output should become inspectable PortaShape structure rather than an unexplained side effect.