# 1view file and Model v1

The public interface is an `.ospec` file with `schemaVersion: "atlas.file/1"`, `model` and `presentation`; legacy `.atlas` files remain accepted under the same contract. `atlas-file.mjs` validates the complete envelope; `file.schema.json` describes its structural grammar. The file owns product content and presentation. The browser has no provider/product-specific inference. See [the authoring instructions](../agent-instructions.md).

`model` uses the existing declarative 1view Model v1 grammar. `model.schema.json` supports editors and generic JSON Schema tooling. `engine.mjs` is the shared executable contract for browser and CLI. Structural validation is followed by semantic reference validation.

## Identity and scope

A model has `schemaVersion: "atlas.model/1"`, positive integer `revision`, and `product: {id, name, defaultView}`. `product.id` is a lowercase slug. Every semantic record starts with `<product>:`. Labels can change; IDs are stable. IDs are unique across all collections.

The collections are:

| Collection | Meaning |
| --- | --- |
| `entities` | Components, interfaces, actors, stores, deployment/trust boundaries, external systems and tables |
| `relations` | Directed edges between entities, including exact column-level FK legs |
| `views` | Named selections and arrangements of shared records; ordered messages or flow steps reference shared components |
| `requirements` | Normative statements, acceptance criteria, affected entities and verification state |
| `evidence` | Source locations, revision/line/hash evidence, observations, accepted requirements and explicit inferences |

## Feature lenses

An optional `extensions["oneview.features"]` record defines viewing scopes over the one canonical graph. The record shape is:

```json
{
  "schemaVersion": "oneview.features/1",
  "features": [
    {
      "id": "sample:feature/checkout",
      "title": "Checkout",
      "summary": "Fictional checkout journey",
      "entryView": "sample:view/checkout",
      "entities": ["sample:entity/cart", "sample:entity/order"],
      "relations": ["sample:relation/cart-to-order"],
      "views": ["sample:view/checkout"],
      "requirements": ["sample:requirement/checkout-confirmation"],
      "evidence": ["sample:evidence/checkout-flow"]
    }
  ]
}
```

The five arrays are required and contain unique valid canonical references. `entities`, `views` and `evidence` must be nonempty; `entryView` must be listed in `views`; every relation endpoint must be included in `entities`; and every listed view must show relevant content. Features are viewing scopes over one canonical graph, not copied models, diagrams or separate artifacts, so records shared across features retain their IDs.

Add `feature-lenses-v1` to `requires` when feature support is essential; an older reader then refuses the file instead of silently overlooking those views. Optional `presentation.featureLayouts` maps feature IDs to ordinary `atlas.layout/1` layouts independently of whole-product `presentation.layout`. The selector filters the canvas, navigation, search, right artifact list and table neighborhoods. Feature scopes are presentation filters, not authorization or security boundaries. Back/Forward and the URL retain feature and view IDs; a URL does not upload or embed a local file, so recipients need the same `.ospec` loaded. Whole product clears the filter. Exports retain the complete canonical model plus features and each arrangement and never serialize a filtered subset. Public chat remains absent; this contract does not promise natural-language chat.

An entity has `id`, `title`, `kind`, `summary`, `status`, `evidence`, optional `group`, `boundary`, `tables`, `contract` and `externalRef`. `boundary` resolves to a boundary entity and cannot form a cycle. `tables` contains table entity IDs. `externalRef: {product, entity, scope}` explicitly declares an external product contract; it does not import that product's authority or assert that an owner model is available.

Table `columns` contain stable `id: "<table-id>.<column>"`, `name`, `type`, `nullable` and `pk`. A foreign key is authoritative in `relations` with `from`, `to`, `fromColumn`, `toColumn`. `constraintColumns` groups composite FK legs: all columns participate together. The optional legacy `fk` column hint is informational; navigation follows relation records. Foreign keys alone do not prove one-to-one cardinality or every CHECK/trigger invariant.

Views use `kind: map | flow | sequence | deployment | tables | spec`. Map/table/deployment views select shared entity and relation IDs, with both endpoints present. A sequence carries participant IDs and ordered `messages: [{relation, note}]`; endpoints and base labels come from the canonical relation. A flow carries view-scoped steps referencing entities, explanatory action detail and explicit transitions. It describes behavior, not an executable orchestration engine. A spec view references requirements. Default positions may be supplied in the model; the user's arrangement is stored separately.

## Specification and evidence

A requirement includes a normative `statement`, nonempty `acceptance` array, affected `entities`, `status`, `evidence`, and `verification`. Use MUST/SHOULD deliberately. Requirements can describe invariants, interfaces, recovery laws, decisions and implementation obligations. Acceptance wording must describe externally visible behavior or durable invariants, not mirror code shape.

Status is a claim class:

- `source`: inspected implementation at a cited revision, not a live assertion.
- `contract`: required behavior; acceptance is tracked separately.
- `proposed`: future/accepted direction, not demonstrated implementation.
- `unverified`: unresolved behavior or authority.
- `synthetic`: fictional portability data.

Verification is independently `source-inspected`, `local-tested`, `reported-local`, `not-verified`, or `synthetic`. Reported earlier local tests are not relabeled as tests run by the current authoring agent. There is deliberately no implicit "deployed" status derived from source presence.

Evidence records have `kind`, `locator`, `scope` and optional `revision`, `lines`, `sha256`, `excerpt`. Source locators can be local paths or references; imported models remain readable when the source checkout is absent because the scope and excerpt travel with the model. They do not establish current source freshness automatically. Absolute local source paths are metadata, not browser-readable file access.

## Evolution

Add new semantic records through patches and link them into relevant views and requirements. Unknown extension fields are retained, allowing product-specific metadata without embedding it in the engine. Prefer an `extensions` object for new experimental data. Existing kinds and statuses remain constrained; add a tested renderer/validator change before using a new kind.

Breaking changes require `atlas.model/2`, an explicit migration command, fixture coverage and preserved v1 exports. Never silently reinterpret old IDs, ownership or verification semantics. An entity rename updates its title; changing identity requires an atomic add/update/remove patch that repairs all references.

Theme files use `atlas.theme/1`; layout files use `atlas.layout/1` and contain `product`, view-keyed positions/camera/page. They are bundled under `presentation.theme` and `presentation.layout` in a public `.ospec` file and are not part of the semantic model digest. The browser namespace is `atlas:v1:` and is reserved for 1view documents.

## Spatial layout extension

`atlas.layout/1` may include `spatial: {version: 1, cameras: {viewId: {x,y,z,distance,yaw,tilt}}}`. Camera IDs resolve to a model view, the reserved `overview`, or the product's focused exploration namespace. All values must be finite; distances are bounded to 100–250,000 world units, positions to ±1,000,000 and angles to ±1 radian. These finite serialization limits are not visible artboard boundaries. The shared engine validates this before import. Legacy 2D layout records remain accepted and retain their positions. Semantic changes do not reset camera or node positions.


## Technical runtime metadata and working planes

Optional entity `technology` names the concrete platform/runtime without a provider enum. `hostedBy` references an entity representing an execution host (for example a Linux VM or Kubernetes cluster); the engine rejects unresolved references and hosting cycles. Existing `boundary` still describes organizational/provider boundaries. `drillView` is a validated view ID for explicit deeper navigation.

Optional relation `protocol` describes the transport or binding; `mode` is `sync` or `async`. `kind` remains an extensible semantic relationship label, including calls, events and foreign keys. A technical view sets `presentation: "technical"`, has explicit entities/relations, and can name `containers` referencing hosting entities. The renderer draws these as enclosing boundaries and retains all internal connections. Technology names are data; neither rendering nor schema validation branches on a particular provider or product.

Authored `positions` are honored unless a separate user layout overrides them. `gridColumns` controls a regular initial arrangement; `inventory: true` marks a complete data view. Table groups and `model.palette` are presentational domain classifications, not new source assertions. `theme.groups` can override domain colors independently of the model.

The working plane is the current authored or focused view. Anchoring is explicit navigation, centering the target without changing its semantic identity. Camera lock prevents incidental gestures; an explicit anchor/plane change unlocks it. Only the active working plane is rendered. Other planes stay available through explicit navigation and do not appear at its edges or overlap it in depth. Background pan is not constrained by the diagram's width or height. Numeric validation still excludes non-finite and unreasonable coordinates; “infinite canvas” describes an open work area, not infinite-precision arithmetic.

In compact table mode all PK/FK and referenced endpoint columns remain visible, plus at most two context columns. Every rendered FK leg ends at its exact source and target column, including vertical and composite relationships. Full column display remains available.

Connections use orthogonal routes around the measured component/table rectangles with clearance. Source and target column row ports remain fixed; alternate sides may be chosen without changing the column identity. Labels avoid card interiors. If overlapping objects physically seal a port, the canvas reports the covered endpoint instead of drawing through an object. This routing contract does not promise globally optimal connector-to-connector spacing. Camera/navigation state and routing geometry do not change the semantic model.

## Resource glyphs

An optional entity/record `glyph` names a symbol from the approved 86-name catalog in `assets/glyphs/manifest.json`, such as `queue`, `mcp-server` or `vector-store`. The public file validator rejects unknown explicit glyph names. Absent glyphs use generic record-kind symbols. No technology/vendor aliases exist in the browser. Explicit glyph choices are file data and never become arbitrary HTML, paths or remote requests. Symbols are generic resource vocabulary, not vendor logos or deployment assertions. All glyphs inherit existing semantic colors.

Original SVGs remain editable under `assets/glyphs/`. The build regenerates `glyph-data.mjs` with `scripts/generate-glyphs.mjs`; runtime renders decorative inline SVG with text/accessible control names retained. Glyph choice does not change object identity, navigation or relationship endpoints. Existing models and browser copies do not require migration.

## Public envelope and browser copies

`presentation.layers` is an ordered array of `{kind,label,color,glyph}` entries for every used view kind. Labels, colors and order are rendered directly. The six supported renderer kinds are grammar, not a product inventory. `presentation.theme` provides all documented tokens. Optional `presentation.canvas` controls table column mode, transition duration and overview title/summary; device reduced-motion always wins. Record `color` can override semantic color. Complete arbitrary record metadata is inspectable in the context panel.

Opening a file validates it before mutation, then previews its product/revision/counts/coverage. Replacing a saved copy is explicit and includes appearance/arrangement; an export action preserves the current copy first. Invalid or cancelled imports leave the current work unchanged. Current file metadata is retained in a single document store; subsequent local layout/theme adjustments are scoped by product and bundled on export. Browser persistence is a convenience, not the durable source: export the file before closing if storage is unavailable.

Optional unknown root, model, record, presentation, theme, layout and extension values are retained. Unsupported required capabilities and major versions refuse to open. Unknown extensions do not automatically acquire custom graphical behavior. JSON formatting/key order are not byte-preserved. Import does not execute embedded code or fetch evidence URLs.

The public validator is `node atlas-validate.mjs product.ospec --strict`. Strict mode additionally checks declared coverage and source-evidence omissions. It cannot prove factual completeness or freshness. The older CLI edits raw `atlas.model/1` documents only; it must not be used as a lossless full-file editor. Legacy browser import is explicitly labeled, adds a presentation template and preserves nonstandard coverage labels as `legacyState` with a conservative partial status.


## Optional staged analysis ledger

`extensions["atlas.analysis"]` uses `atlas.analysis/1`, current authoring protocol `1.1.0` (legacy `1.0.1` remains accepted). It embeds scope, source roots/manifest/fingerprints, file and discovery dispositions, entity and relation dossiers, per-trigger scenario analyses, detailed area assessments, count reconciliations, completion checks, gaps, discovery closure and append-only stage history. Source evidence binds to a manifest entry with `sourceFile: "root:path"` and its `sha256`.

Eight stages progressively refine one model: scope, inventory, structure, connections, behavior, obligations, views and reconcile. Stage receipts record iteration, input digest, dependencies, evidence and produced record IDs. Later changes require new dependent receipts; stale stages cannot claim completion. A partial file is still a valid viewer document. The base `atlas.file/1` contract remains unchanged; the browser preserves this optional ledger and exposes it through complete-file inspection, without a dedicated stage dashboard.

`analysis-audit.mjs` adds authoring gates beyond the file validator; `check product.ospec --root main=PATH --complete` requires current source enumeration. The single public `agent-instructions.md` includes this checker and its dependencies in one extractable block. Its canonical prose is `docs/AUTHORING_PROTOCOL.md` and `docs/AUTHORING_WORKBOOK.md`; regeneration is `node scripts/package-instructions.mjs`. Protocol 1.1 additionally embeds `work` (`atlas.work/1`), including source identities, detector leads, mandatory tasks, answers, explicit dependencies and resumable receipt history. `summary` is derived from the current model and work; hand-edited stale counts fail the audit. Source line ranges are checked against scanned file lengths where available. Complete results require a closed investigation for each entity, relation and flow, plus a final review. Hosting, table engine/ownership, isolated records and drill navigation receive extra checks with evidenced exceptions for legitimate cases. Checks enforce integrity/accounting, not factual interpretation or live completeness.


### Table neighborhoods and database technology

Every table card displays its entity `technology` as a separate tag, independent of its domain/group. Authors should populate it from datastore evidence, including the engine and hosting technology when known. Legacy records without it display “Technology unspecified”; the viewer never guesses. Two identically named tables in separate stores retain separate stable IDs.

**Show connections** is a reversible navigation lens on the working plane. The `neighbors=<table-id>` URL parameter selects that table and all directly related table entities in either direction, including neighbors outside the authored diagram. In compact/key mode, the neighborhood shows the related columns and primary keys; **Show all columns** reveals the full schema. Returning removes the temporary column filter; an explicit change to All columns remains selected. Only the root’s declared table relationships appear; there is no recursive expansion. The current source file is the authority for the links and exact column endpoints. Self and composite relationships retain every declared leg.

Unrelated tables fade out; connected tables move into a compact layout. Return restores the prior plane arrangement and camera. Back/Forward and links retain the selected neighborhood. Temporary neighborhood positions do not overwrite the full schema’s exported layout. Per-table anchors, columns, relationship selection, panning, zooming and details remain available; opening a connected table’s neighborhood is an explicit action. Reduced-motion preferences remove the transition. High-degree tables retain all direct neighbors; zoom and pan remain available when the neighborhood is larger than the viewport.

Connectors route around measured card bounds with parallel lanes and a shared congestion cost. Exact column ports may share their short terminal segment; long shared routes preferentially separate. Hovering/selecting a column or relationship highlights its endpoints. This is an obstacle/congestion heuristic, not a claim that every possible imported graph can be drawn without crossings.