# The `.posh` Artifact Model

## Role of `.posh`

A `.posh` file is the durable language of PortaShape. The workspace is where a system is explored and changed; `.posh` is how the useful explanation of that work becomes portable, reviewable, reusable, and executable.

A `.posh` artifact can describe not only how one field maps to another, but also the systems involved, the controls used to operate them, the transforms and policies applied, the workflow that executed them, and the evidence produced.

## Design goals

The format should be:

- human-readable and machine-readable;
- JSON-based with canonical formatting;
- small for simple cases;
- composable for large systems;
- typed and versioned;
- inspectable and source-control-friendly;
- explicit about uncertainty, authority, loss, and unresolved values;
- extensible through namespaced additions;
- safe to share without embedding raw secrets.

## Artifact kinds

A `.posh` document declares a primary `kind`. Core kinds are:

### `system`

A system declaration or snapshot containing elements, values, relationships, settings, options, runtime observations, versions, and capabilities.

### `surface`

A generated or manually composed operational interface: controls, views, layout, queries, actions, permissions, and element bindings.

### `mapping`

Correspondence between source and destination elements, including direction, priority, conditions, transformations, fallbacks, and conflict rules.

### `transform`

Reusable conversion or generation logic with typed inputs, outputs, dependencies, trust, loss, and validation behavior.

### `workflow`

A sequence or graph of operations, approvals, jobs, retries, and results.

### `policy`

Validation, permission, safety, accessibility, brand, compatibility, or operational rules.

### `snapshot`

A point-in-time system state suitable for backup, comparison, migration, diagnostics, rollback, or environment reproduction.

### `run`

A durable execution report containing resolved inputs, versions, decisions, outputs, warnings, validation, approvals, and provenance.

### `library`

A package manifest for adapters, schemas, vocabularies, controls, surfaces, mappings, transforms, workflows, policies, examples, and documentation.

### `bundle`

A composed artifact that imports or embeds multiple kinds for a complete product, migration, project, or reusable capability.

## Conceptual root

```json
{
  "portaShape": {
    "formatVersion": "0.1",
    "kind": "bundle",
    "id": "example.bundle",
    "name": "Example Bundle",
    "description": "A composed system-shaping package.",
    "imports": [],
    "systems": [],
    "elements": [],
    "surfaces": [],
    "mappings": [],
    "transforms": [],
    "workflows": [],
    "policies": [],
    "settings": {},
    "options": {},
    "extensions": {},
    "metadata": {}
  }
}
```

Only fields relevant to the artifact kind need to be present.

## Systems and endpoints

A mapping or workflow can declare several systems rather than only one source and one destination. Each system includes:

- `id` and `type`;
- adapter and adapter version;
- environment;
- schema references;
- capabilities;
- credential or connection profile references;
- compatibility information;
- optional discovery snapshot.

Simple examples may retain `source` and `destination` aliases for readability.

## Element references

Element references can be:

- local IDs;
- source-native paths;
- semantic IDs;
- qualified references such as `systemId#elementId`;
- queries that resolve to sets of elements;
- imported library references.

Stable IDs should survive presentation changes and, where possible, schema evolution.

## Settings and options

The distinction between settings and options is first-class.

- `settings` represent global, structural, environmental, or system-level choices.
- `options` represent user-, account-, audience-, session-, or use-case-focused selections.

Artifacts may include mappings within each scope, but they must not silently collapse a personal option into a global setting or vice versa.

## Mapping records

A mapping record can declare:

- ID and human description;
- source and destination references;
- relation type;
- operation: copy, map, translate, transmute, synchronize, derive, generate, ignore, or unresolved;
- transform or transform pipeline;
- input and output types;
- conditions;
- defaults and fallbacks;
- lookup tables;
- direction and reversibility;
- loss characteristics;
- priority and dependency order;
- conflict policy;
- validation and assertions;
- confidence and explanation;
- approval status and notes.

## Transform records

Transforms should prefer structured forms such as:

- unit conversion;
- enum lookup;
- string template;
- formula;
- field combine or split;
- object reshape;
- path or URL rewrite;
- token conversion;
- schema projection;
- component generation;
- asset processing;
- sandboxed function;
- external service procedure;
- AI-assisted procedure with captured prompt, model/runtime metadata, constraints, and reviewed structured output.

## Surface records

A surface can describe:

- bound elements and queries;
- control types and renderer preferences;
- grouping, layout, and navigation;
- views, tables, previews, timelines, and graphs;
- actions and workflow triggers;
- role and permission rules;
- temporary, proposed, and committed states;
- event contracts and mutation boundaries;
- accessibility requirements;
- target renderer.

This allows a generated internal tool or runtime panel to be saved and reused just like a mapping.

## Workflow and execution

A workflow describes intended steps. A run records what actually happened.

A workflow step may:

- discover or refresh a system;
- request input;
- calculate or transform;
- validate;
- require approval;
- write or invoke;
- wait for a job or event;
- compare results;
- generate output;
- create a snapshot;
- publish a report;
- compensate or roll back.

Runs resolve imported versions and record exact inputs, outputs, environment, actor, timing, and results.

## Composition and layering

Libraries and projects can layer artifacts:

1. platform base;
2. organization standard;
3. project specialization;
4. environment override;
5. account or user options;
6. run-time proposal or temporary override.

Layer rules must identify whether a field replaces, merges, appends, removes, or conflicts. The resolved artifact should be inspectable before execution.

## Snapshots and comparison

A snapshot can capture:

- schemas and values;
- settings and options;
- design tokens and component defaults;
- routes, content, assets, and metadata;
- feature flags, permissions, and policies;
- animation parameters and runtime observations;
- adapter and system versions.

Comparisons produce added, removed, changed, retyped, drifted, unresolved, and incompatible results that can be promoted into a mapping or workflow.

## Provenance and traceability

Every generated destination value should be traceable to:

- source values;
- mapping and transform IDs;
- artifact and library versions;
- actor and approval;
- execution environment;
- validation outcomes;
- loss or inference;
- subsequent drift.

## Error and unresolved representation

Errors and unresolved values are explicit arrays or records, not discarded log text. They include severity, affected elements, reason, candidate resolution, fallback, continuation policy, and supporting context.

## Security and trust

A `.posh` file should:

- reference secrets rather than contain them;
- declare required capabilities;
- identify trusted and untrusted transforms;
- support signatures and integrity hashes;
- make external code or service execution visible;
- support environment and field restrictions;
- be safe to parse without executing procedures.

## Versioning

The format distinguishes:

- file format version;
- core schema version;
- extension versions;
- adapter versions;
- source and destination system versions;
- transform runtime versions;
- library package versions.

Compatibility should be checked before execution, and migrations between format versions should themselves be explicit and testable.

## Included examples

The `examples/` directory contains MVP-ready playground fixtures for the three dozen simple examples and upgraded legacy catalog examples, progressing from copy/combine/split examples through structural transmutation, design-token conversion, schema/UI generation, API/table translation, workflow status mapping, asset extraction, visual componentization, and complete site transfer, plus a `portashape-self-description.posh` bundle. They are illustrative and should remain clearly labeled non-normative until the formal schema is implemented.