# Product and security glossary

Al-Amr uses a small set of domain terms with deliberate boundaries. Use the
definitions below in product copy, documentation, APIs, and code review. A
familiar word such as “environment,” “release,” or “permission” may have a
narrower meaning here than it does in ordinary web development.

Code identifiers such as `environment_revision` and `trusted_library` are shown
exactly as they appear in public contracts.

## Product and ownership

### Environment

A destination that a user enters and experiences. An Environment has its own
stable Registry ID, owner, bundle entry/version, entry policy, immutable
revisions, presence identity, health record, and exact Plugin installation set.
Its developer owns the scene, framework, experience, and optional backend; the
platform holds and serves the reviewed frontend bytes.

An Environment is not a page inside the Developer Portal and is not a Plugin.

### Plugin

A versioned, installable capability used by an Environment. A Plugin is the
public unit of discovery, installation, compatibility, review, and
publication. It may provide frontend adapters, backend components, or both.

A backend service is not a separate Marketplace product; it is an optional
BackendComponent of a Plugin.

### App

An independently authored immutable bundle a person opens inside an
Environment. The desktop AppHost serves it from a platform-owned App origin in
a sandboxed frame the Widget owns; it never imports Environment code, reads the
scene, or holds a Runtime credential. Both halves of an App belong to the App
publisher: its backend is `apps/<app>/packages/backend`, moved there by
[ADR-0080](../decisions/ADR-0080-a-product-owns-its-own-halves.md) from the
`services/` placement that
[ADR-0068](../decisions/ADR-0068-app-owned-backends.md) first chose.

An App is not a Plugin. A Plugin extends an Environment from inside that
Environment's own bundle; an App is a separate document that reaches the world
only through Host Services.

### Widget

The platform's own surface inside every Environment: the App frame, the
notification inbox, and the companionship panel. The Widget opens a held App
bundle in an origin-checked iframe and owns capability grants, host authority,
and request deadlines; the Environment receives only typed interaction state.
Display-mode changes preserve the App document and session and arrive through
the presentation-change protocol.

An App or an Environment must never mount a second platform inbox or reach into
Widget DOM.

### Project

The mutable management container used by an owner in Console, the Management
API, and the `alamr` CLI. A Project has type `environment`, `app`, or `plugin`. Editing
a Project creates new immutable candidate snapshots; it does not rewrite a
published target.

A `projectId` is not an `environmentId` or `pluginId`.

### Publisher

The public identity that owns handles and Projects. Publisher verification is
Registry state. Verification identifies the Publisher status recorded by the
platform; it is not a claim that arbitrary frontend code is sandboxed or safe.

### Registry

The source of truth for public identity, catalog records, immutable revisions
and releases, artifact validation, publication state, trust, compatibility,
settings, Runtime authorization, Plugin Grants, health, and presence.

UI code, a 3D scene, package metadata, or copied documentation must not replace
Registry state as authority.

### Developer Portal and Console

The Developer Portal is the public server-rendered Learn and Discover surface:
documentation, catalog, Plugin, Environment, Publisher, reference, and status
pages. Console is its authenticated management area.

Console is a client of the same public Management API used by CLI and CI; it is
not a private source of product authority.

### Hub

The ordinary Environment named `environment-zero`. Hub uses the same public
SDK, entry flow, Registry APIs, and Plugin installation model as every
independent Environment. It has no privileged Plugin path.

### Zone

An application-local scene inside Hub, addressed by `/z/:slug`. Zones share
the Hub origin, Runtime, presence identity, settings, exact Plugin
installations, Environment revision, and persistent R3F canvas. A Zone is not a
Registry entity, Project, Environment, or publication target.

### Place

Where a person is, in the Environment's own words: an optional Zone and an
optional location, either of which may be absent
([ADR-0075](../decisions/ADR-0075-an-environment-says-where-you-are.md)). An
omitted Zone is not missing data — it is a world saying it has no such division,
and an App that prints only what it was given renders both kinds of world
without knowing which it is in. A location carries an id only when the
Environment declared the place, which is what separates an address something may
aim at from a description of a bench.

## Identities and immutable records

### Stable identity

The Registry ID that continues to identify an Environment or Plugin across
slugs, package names, hosting providers, and immutable versions. Public package
name and catalog slug are not platform identity.

### EnvironmentManifestRevision

An immutable snapshot of Environment entry, portal presentation,
capabilities, and exact Plugin installations. Publication activates a reviewed
revision; later editing creates another revision.

### PluginRelease

An immutable, SemVer-addressed snapshot of Plugin metadata, frontend adapters,
backend component contracts, settings schema, permissions, disclosures,
compatibility, documentation, and package artifact identity.

Changing the manifest or package bytes under an existing Plugin version is a
conflict. Publish a new version instead.

### BackendComponent

An optional data-plane capability declared inside a Plugin release. Its
contract defines component identity, protocol, Grant scopes, and public
context. A backend component receives authority only from a verified,
short-lived Plugin Grant.

### BackendDeploymentRevision

An immutable snapshot of one BackendComponent's live endpoint, optional health
URL, and public non-secret configuration. Deployment revisions are reviewed
and published separately from the Plugin release. Secrets stay in deployment
infrastructure.

### PackageArtifact

The exact package bytes associated with a Plugin release plus their provider,
package specification, size, integrity, and validation state. A managed
artifact is uploaded to Al-Amr; an npm artifact is resolved by Registry and
mirrored after validation.

Only the artifact-validator boundary is allowed to inspect and validate managed
package bytes. Registry metadata alone is never proof that bytes are safe.

### `al-amr.lock.json`

The Environment lockfile generated by `alamr add`. It binds each installation
to a Registry Plugin ID, release ID and version, adapter, artifact, package
specification, and SHA-512 integrity. Do not hand-edit it.

## Publication

### Publication target

The immutable object under review: an `environment_revision`,
`plugin_release`, or `backend_deployment_revision`.

### PublicationSubmission

The workflow record that binds one target to its snapshot digest, ordered
artifact snapshot digest when applicable, visibility, channel, checks, actor,
and publication state.

The submission does not make mutable Project data authoritative. Review and
publication remain bound to the frozen target and digests.

### Snapshot digest and artifact digest

The snapshot digest identifies the exact immutable target. For a Plugin
release, the artifact digest identifies the exact ordered set of registered
artifacts frozen when the submission is created. Review and final publication
fail if those values no longer match.

### Visibility

`unlisted` or `public`. Visibility is selected on a publication submission and
is separate from its workflow state and channel.

### Channel

`preview`, `beta`, or `stable`. A channel communicates release maturity; it
does not bypass checks, review, artifact validation, or immutable versioning.

### Yank and suspend

`yanked` and `suspended` are terminal administrative states reachable from
`published`. Both require a reason in the transition contract and remove the
target's active authority. The current runtime revokes affected sessions or
Plugin Grants according to target type.

A yanked Plugin version remains identifiable for reproducibility, but the CLI
rejects adding it to a new Environment.

### Rollback

Moving a Project's active pointer to an earlier eligible, still-published
Environment revision or Plugin release. Rollback does not edit either snapshot
and requires a recorded reason. A blocked or non-published target is not
eligible.

## Runtime and authorization

### Browser SSO

The Registry-owned browser sign-in session shared across Environment entry and
Developer Portal login. Each Environment still receives an isolated,
origin-bound token and Runtime session. Browser SSO is separate from CLI login,
CI project tokens, and other browser or device sessions.

### Authorization Code with PKCE

The public-client entry protocol used by Environments and CLI. PKCE S256 binds
the one-time authorization code to the client that created the verifier.
Redirect URIs are registered exactly; a code, verifier, state, or redirect URI
cannot be substituted safely.

### Runtime session

The Registry record for one authorized Environment page or device. A session
may be `standby`, `active`, `superseded`, released, expired, or revoked.
Authorization and active ownership are separate.

### App session

Short-lived authority for one exact App revision, fenced by the parent
Environment Runtime lease, host generation, display mode, and permission-set
digest. Its `appActorSub` is pairwise to account and App, so an App recognizes
its own user across Environments without ever receiving the raw account subject;
it is distinct from a Plugin `actorSub`. An App whose manifest carries a
`backend` block is a confidential client and its own backend signs the exchange,
because a browser frame cannot hold the key that proves it
([ADR-0074](../decisions/ADR-0074-an-app-proves-its-publisher.md)).

### Principal

The private account for which Registry coordinates active
Runtime ownership. One principal may hold exactly one active Al-Amr
Environment Runtime at a time.

### Runtime lease and fence

The short-lived, monotonically fenced proof that a Runtime session currently
owns active execution. Protected Runtime requests carry the session ID, exact
lease ID, and lease version. A stale fence fails with `409`; unavailable
production coordination fails closed with `503`.

### Superseded Runtime

A formerly active Runtime displaced by a newer activation. Its Plugin Grants
are revoked, presence is removed, and compliant Plugin resources are stopped.
Focus alone does not reclaim ownership; the user must explicitly activate the
page.

### Control channel

A read-only, session- and origin-bound channel kept by an inactive page to
receive activity and browser-wide sign-out events. Its credential has no
Runtime lease. It cannot send presence, request Plugin Grants, change settings,
or run Plugin UI.

### Presence

Registry-backed evidence that an Environment Runtime is connected. The SDK
reports connected presence only after authorization, Runtime activation, and a
successful heartbeat. A hard-coded online flag is not truthful presence.

### Plugin Grant

A short-lived signed token for one exact installed Plugin release and published
backend deployment. It carries audience, scopes, origin, expiry, immutable
context, anonymous status, and the Runtime lease fence. Backend code verifies
it locally and introspects mutable lease and revocation state.

### Pairwise actor ID

A stable user pseudonym scoped to one Plugin. Backend components receive this
pairwise identifier rather than the ecosystem-wide user ID.

## Plugin trust and permissions

### `trusted_library`

The v0.x frontend Runtime class. Plugin package code executes in the same
JavaScript realm and with the same browser authority as the host Environment.
It is trusted host-library code, not isolated remote code.

### Platform permission

A declared capability that Al-Amr APIs can enforce, such as settings or Plugin
Grant access. Platform permissions do not restrict arbitrary JavaScript,
browser APIs, or network behavior outside the platform.

### Browser requirement

A declared browser capability the Plugin needs, such as media or device access,
plus whether it is required and why. It is a disclosure, not authority granted
by Registry.

### Network and data disclosure

The Plugin's declared external origins, reason for access, collected and shared
data, retention, and optional privacy policy. Review can inspect these
declarations; the declarations are not a browser network sandbox.

### Grant scope

An operation a backend component accepts through a verified Plugin Grant.
Grant scopes are distinct from frontend platform permissions and browser
requirements.

## Companionship and notifications

### Companion

A person an account is connected to on the platform rather than inside a world.
A companion list crosses to an App only through an interactive consent ceremony
rendered on a Registry origin, and only for the account that owns the list
([ADR-0070](../decisions/ADR-0070-companions-for-apps.md)). What crosses is the
App-pairwise subject plus the presented name and avatar. A companion's own
companions, any cross-App correlation of the same person, any marker anchored to
an avatar, and any path that reaches an Environment stay prohibited.

### Invite code

The standing, derived, hundred-bit code every account holds — `alamr-` and
twenty symbols — which is the only address in the companionship layer
([ADR-0125](../decisions/ADR-0125-companionship-is-addressed-by-a-standing-invite-code.md)).
A person copies it, hands it over out of band, and whoever pastes it in the
client's own panel sends a companionship request. Only a digest is stored;
«کدِ تازه» rotates it and the old code stops resolving.

### Companionship request

What pasting a code creates: one pending request the holder accepts, declines
for thirty days, or blocks permanently, answered in the desktop panel on the
device plane. Every refusal a paste can meet answers as one identical negative,
and the card carries zero bytes the sender authored.

### Notification source

The App or Environment a notice came from. A source declares its event
vocabulary in its manifest before it may publish anything, and the identity
shown on a notice comes from Registry rather than from the words the source
sent. A source is not an HTTP origin — in Persian those are one word apart and
lead to opposite subsystems, which is why the term table below exists.

### Notification treatment

How loud one notice is, decided by the platform rather than requested by the
source ([ADR-0085](../decisions/ADR-0085-one-notice-one-treatment.md)). There
are exactly three: `announce` is the inbox, the unread mark and a transient card
drawn over the world; `file` is the inbox and the unread mark; `mute` is the
inbox, silently. `mute` still writes the row, because silencing is an
instruction about attention and not about memory.

## Settings and concurrency

### Settings scopes

The five layers from highest to lowest precedence are:

```text
session > user_environment > user > environment > plugin_default
```

`session` is local and not persisted. `user_environment` applies to one user in
one Environment; `user` is that user's global fallback; `environment` belongs
to the immutable Environment configuration; `plugin_default` comes from the
Plugin schema.

### Settings provenance

The parallel tree that identifies which scope supplied each resolved leaf.
An inherited value is not copied into a persisted user layer.

### Settings ETag

The aggregate concurrency token returned in both the response body and HTTP
`ETag` header. Persistent writes and resets use it in `If-Match`. A stale value
fails with `412` instead of silently overwriting another change.

## Persian terms

A bug report arrives in Persian, and the word in it decides which subsystem an
agent opens next. The first two rows are the pair that costs the most: two
different English concepts whose Persian words differ by one letter, leading to
opposite halves of the repository.

| Persian         | English               | Where the code is                                             |
| --------------- | --------------------- | ------------------------------------------------------------- |
| منبع            | notification source   | `services/registry/src/notifications/`                        |
| مبدأ            | HTTP origin           | CSRF and iframe origin checks, mostly in the Developer Portal |
| اعلان           | notice                | `services/registry/src/notifications/persist.ts`              |
| محیط            | Environment           | `environments/`                                               |
| افزونه          | Plugin                | `plugins/`                                                    |
| اپ              | App                   | `apps/`                                                       |
| همراه           | companion             | Registry companionship, never an Environment                  |
| همراهی          | companionship         | the platform layer that owns the companion list               |
| کدِ دعوت        | invite code           | the standing address of companionship, ADR-0125               |
| درخواستِ همراهی | companionship request | one pending request per pasted code                           |
| قدم             | contribution credit   | «هم‌قدم», the internal build tool in `apps/hamqadam`          |

For lifecycle details continue with
[Publication lifecycle](/docs/publish/publication-lifecycle). For operational
failures use [Troubleshooting](/docs/errors/troubleshooting), and for the full
trust model read [Trust and security](/docs/security).