# PortaShape 0.1 Conceptual Schema

## Status

This is a coherent **conceptual draft**, not a final normative specification. It consolidates the uploaded concept and example materials into a single artifact model suitable for implementation planning and schema prototyping.

## Serialization

- File extension: `.posh`
- Canonical serialization: UTF-8 JSON
- Root key: `portaShape`
- Format version: semantic or compatible version string beginning with `0.1`
- Unknown namespaced extension keys should be preservable even when not executable.

## Minimal artifact

```json
{
  "portaShape": {
    "formatVersion": "0.1",
    "kind": "mapping",
    "id": "example.mapping",
    "name": "Example Mapping",
    "mappings": []
  }
}
```

## Root fields

| Field | Required | Meaning |
| --- | :---: | --- |
| `formatVersion` | yes | `.posh` serialization version. |
| `kind` | yes | Primary artifact kind. |
| `id` | recommended | Stable artifact identity. |
| `name` | recommended | Human-readable name. |
| `description` | no | Purpose and context. |
| `imports` | no | Other artifacts or library packages. |
| `systems` | by use | Connected or referenced systems. |
| `elements` | no | Embedded element definitions or snapshot content. |
| `surfaces` | no | Control and view compositions. |
| `mappings` | no | Element relationships with execution semantics. |
| `transforms` | no | Reusable operations. |
| `workflows` | no | Orchestrated steps and approvals. |
| `policies` | no | Validation, permissions, and governance. |
| `settings` | no | Global or structural configuration. |
| `options` | no | User/account/session selections. |
| `unresolved` | no | Explicit unresolved values or relationships. |
| `extensions` | no | Namespaced additions. |
| `metadata` | no | Authors, dates, versions, signatures, notes, provenance summary. |

## Artifact kinds

Allowed initial values:

```text
system | snapshot | surface | mapping | transform | workflow | policy | run | library | bundle
```

A parser may support legacy or experimental kinds through an extension or migration layer.

## System declaration

```json
{
  "id": "source-site",
  "type": "website",
  "adapter": {
    "id": "example.website-adapter",
    "version": "1.0.0"
  },
  "environment": "production",
  "connectionProfile": "secrets://connections/source-site",
  "schema": "library://schemas/example-site@1",
  "capabilities": ["read", "observe"],
  "version": "2026.07"
}
```

A system declaration must not require raw credentials.

## Element declaration

```json
{
  "id": "source-site#theme.colors.primary",
  "system": "source-site",
  "kind": "value",
  "path": "theme.colors.primary",
  "name": "Primary color",
  "semanticRole": "color.action.primary",
  "valueType": "color",
  "scope": "settings",
  "authority": "source-site",
  "capabilities": ["read", "propose"],
  "constraints": {
    "format": "hex"
  }
}
```

## Scope values

Initial core scopes:

```text
settings | options | runtime | content | code | derived | reference | secret-reference
```

Custom scopes use namespaced values.

## Mapping declaration

```json
{
  "id": "map-primary-color",
  "source": "source-site#theme.colors.primary",
  "destination": "destination-site#brand.actionColor",
  "relation": "semantic-equivalent",
  "operation": "translate",
  "transform": "color.hex-to-rgb",
  "direction": "source-to-destination",
  "loss": "lossless",
  "confidence": 0.98,
  "explanation": "Both values control the primary interactive brand color.",
  "validation": ["policy://brand/primary-color"]
}
```

## Operations

Initial operation values:

```text
copy | map | translate | transmute | derive | generate | synchronize | ignore | unresolved
```

## Relationship cardinality

A mapping can use string references or arrays:

- one source, one destination;
- one source, multiple destinations;
- multiple sources, one destination;
- multiple sources, multiple destinations.

## Transform declaration

```json
{
  "id": "spacing-scale-from-base",
  "kind": "formula",
  "inputs": [
    {"name": "base", "type": "number"}
  ],
  "outputs": [
    {"name": "scale", "type": "object"}
  ],
  "expression": {
    "space.1": "base * 0.25",
    "space.2": "base * 0.5",
    "space.3": "base",
    "space.4": "base * 1.5"
  },
  "deterministic": true,
  "loss": "generated",
  "trust": "declarative"
}
```

## Loss values

```text
lossless | lossy | approximate | inferred | generated | non-deterministic | unresolved
```

Reversibility is a separate boolean or strategy declaration.

## Surface declaration

```json
{
  "id": "theme-tuner",
  "name": "Theme Tuner",
  "renderer": "library://portashape/web-native",
  "bindings": [
    {
      "element": "source-site#theme.colors.primary",
      "control": "color",
      "mode": "propose-and-preview"
    }
  ],
  "layout": {
    "type": "inspector"
  },
  "permissions": {
    "commit": ["role:designer-lead"]
  }
}
```

## Event contract

```json
{
  "id": "theme-preview-applied",
  "kind": "fact",
  "producer": "surface:theme-tuner",
  "scope": "workspace",
  "payloadSchema": {
    "artifactId": "string",
    "changedElementIds": "string[]"
  },
  "version": "1"
}
```

Events should describe domain meaning rather than implementation detail.

## Workflow declaration

```json
{
  "id": "promote-theme",
  "steps": [
    {"id": "snapshot", "action": "snapshot", "system": "destination-site"},
    {"id": "simulate", "action": "simulate", "mapping": "theme-mapping"},
    {"id": "validate", "action": "validate", "policies": ["brand", "accessibility"]},
    {"id": "approve", "action": "approval", "role": "design-lead"},
    {"id": "execute", "action": "apply", "mapping": "theme-mapping"},
    {"id": "verify", "action": "validate-destination"}
  ]
}
```

## Policy declaration

Policies may contain assertions, rules, severity, scope, required evidence, and gating behavior.

```json
{
  "id": "all-source-routes-resolved",
  "assert": "count(unresolved where category == 'route') == 0",
  "severity": "error",
  "gate": "execution"
}
```

## Unresolved declaration

```json
{
  "id": "unresolved-widget-legacy-carousel",
  "source": "source-site#components.legacyCarousel",
  "reason": "Destination has no equivalent component or adapter capability.",
  "severity": "warning",
  "candidates": ["destination-site#components.gallery"],
  "requiresDecision": true,
  "canContinue": true
}
```

## Run report

A run artifact should resolve exact imported versions and include:

- workflow or mapping ID;
- actor;
- start and completion times;
- source and destination system versions;
- artifact, adapter, transform, and policy versions;
- resolved inputs;
- writes and outputs;
- approvals;
- validation results;
- warnings, errors, unresolved values;
- provenance links;
- rollback or compensation information;
- final status.

## Imports and layering

```json
{
  "imports": [
    {
      "ref": "library://platform-a-to-b@2",
      "as": "base"
    },
    {
      "ref": "./organization-overrides.posh",
      "as": "organization"
    }
  ]
}
```

Layer resolution must be deterministic and reveal conflicts before execution.

## Extensions

Extension keys use a reverse-domain or package namespace:

```json
{
  "extensions": {
    "dev.portashape.visual-regression": {
      "baseline": "artifact://screenshots/theme-v4"
    }
  }
}
```

Core parsers preserve unknown extensions. Execution requires a compatible extension provider.

## Canonical formatting

A future normative specification should define:

- key order or canonicalization algorithm;
- numeric and date normalization;
- stable reference resolution;
- hashing and signatures;
- schema URIs;
- comments or annotation strategy;
- partial-file composition;
- migration between versions.

## Backward relationship to the twelve examples

The extracted examples use a smaller conceptual shape with `source`, `destination`, `mappings`, `settings`, and `options`. They remain valid teaching artifacts. An implementation can either support them directly as a simple profile or migrate them into the richer multi-system schema described here.