# Sylphx Platform

> Architecture target and discovery guide. This file does not certify that a
> target capability is currently deployed or live.

Sylphx Platform is one provider-neutral commercial application and capability
platform built on four disjoint primitives:

- Resource: addressable mutable or lifecycle-managed state.
- Operation: one admitted durable effect.
- Event: one retained immutable fact.
- Artifact: immutable content or evidence addressed by digest.

The target has one canonical typed public contract. REST/OpenAPI, SDK, CLI,
Console, MCP, validation, and UI descriptors are generated projections. Generic
Functions, Tasks, Runs, and Triggers are not root target concepts.

## Agent and operator contract

Every admitted action is discoverable, revision-safe, idempotent, authorized,
metered, audited, observable, and evidence-linked. Risky actions use plan and
apply; destructive actions require confirmation bound to the plan digest,
target revision, Principal, Policy decision, cost bound, and expiry.

MCP is an optional generated adapter. MCP Resources and the optional Tasks
extension project Platform Resources and Operations; they do not own a second
schema, credential, business, billing, or lifecycle plane. Platform remains
operable through API, generated SDK, CLI, Console, and automation when MCP is
unavailable.

## Current availability

Use the currently published generated API discovery, shipped CLI help, and
current public documentation to determine what is available now. Absence from
current discovery means unavailable. Do not infer current behavior from this
target summary, archived endpoint lists, ADRs, source presence, or historical
BaaS names.

- [Public documentation](https://sylphx.com/docs)
- [Current API discovery when published](https://api.sylphx.com/v1/openapi.json)
- [Service status](https://status.sylphx.com)
- [Platform source and constitutional documentation](https://github.com/SylphxAI/platform)

---

# Full documentation


## API-REFERENCE.md

# Sylphx Platform API Reference — Superseded Snapshot

**Status:** Superseded on 2026-08-07
**Archived snapshot:** [`docs/archive/superseded-platform-architecture-2026-08-07/root/API-REFERENCE.md`](docs/archive/superseded-platform-architecture-2026-08-07/root/API-REFERENCE.md)

The archived file documented a predecessor handwritten surface and must not be
used as current or target API authority.

- Target wire authority: Protobuf plus Buf under the
  [Platform Constitution](docs/constitution/platform-constitution.md).
- Target lifecycle: [Resource, Operation, Event, and Artifact Contract](docs/specs/2026-08-07-resource-operation-event-artifact-contract.md).
- Current deployed behavior: exact generated descriptors, service discovery,
  immutable Artifact identity, and trusted live readback only.

Absence from current discovery means unavailable; neither this tombstone nor the
archive is a compatibility promise.

## PLATFORM-USER-GUIDE.md

# Platform User Guide — Superseded Snapshot

**Status:** Superseded on 2026-08-07
**Archived snapshot:** [`docs/archive/superseded-platform-architecture-2026-08-07/root/PLATFORM-USER-GUIDE.md`](docs/archive/superseded-platform-architecture-2026-08-07/root/PLATFORM-USER-GUIDE.md)

The archived guide describes predecessor commands, endpoints, generic Tasks,
and implementation-specific behavior. It is not a target contract or fresh live
certification.

Use generated public discovery and the shipped CLI help for current behavior.
Use the [Agent-Native Operations Surface](docs/specs/2026-08-07-agent-native-operations-surface.md)
and the [North Star](docs/reference/north-star-architecture.md) for the clean
target. Missing current discovery is a product gap, not permission to use an
archive or internal interface.

## docs/reference/resources.md

# Resource Reference

**Status:** Derived reference; cannot amend the Platform Constitution
**Revision:** 2026-08-07
**Binding contract:** [Resource, Operation, Event, and Artifact Contract](../specs/2026-08-07-resource-operation-event-artifact-contract.md)

This file is a concise lookup. It does not define a second Resource model.

## Definition

A Resource is an addressable mutable or lifecycle-managed entity. A retained
fact is an Event; immutable content is an Artifact; an admitted effect is an
Operation.

## Required Resource properties

- strongly typed capability schema;
- canonical hierarchical name and immutable uid;
- one home authority partition and semantic writer;
- opaque etag and explicit generation preconditions;
- typed `spec` and `status` when reconciled;
- bounded generation-aware Conditions;
- typed owner, Policy, sensitivity, retention, and placement class;
- links to Operations, Events, Artifacts, telemetry, cost, and Evidence.

## Standard methods

A Resource exposes the applicable subset of `Get`, `List`, `Create`, `Update`,
`Delete`, `Undelete`, `Plan`, and `Watch`. Domain actions use typed custom
methods and still return Operations.

## Resource name examples

```text
organizations/{organization}
organizations/{organization}/projects/{project}
organizations/{organization}/projects/{project}/services/{service}
organizations/{organization}/projects/{project}/batchJobs/{batch_job}
organizations/{organization}/projects/{project}/buckets/{bucket}
organizations/{organization}/projects/{project}/operations/{operation}
```

Names use product vocabulary. Provider implementation, orchestration, placement,
and scheduling identities are not canonical public names.

## Desired and observed state

- callers and authorized controllers write desired `spec`;
- only the owning authority writes observed `status`;
- `observed_generation` states which desired generation was evaluated;
- `Ready=true` means the customer-visible postcondition was observed;
- history is represented by Events and Operations, not unbounded status arrays.

## Deletion

Deletion fences new incompatible effects, applies typed retention/finalization,
proves external postconditions, emits terminal Event and Evidence Artifact, and
then removes or tombstones the Resource according to policy. Force deletion is
a separate destructive Operation with explicit data-loss and orphan semantics.

## Not Resources

The following are projections or other primitives:

- orchestration objects and provider instances;
- dashboard rows and reports;
- mutable release tags;
- Operation attempts and effect receipts;
- retained domain facts;
- immutable build outputs and evidence bundles.

## docs/reference/database-tiers.md

# Managed Database Service Classes

**Status:** Derived reference; cannot amend the Platform Constitution
**Authority:** [Platform Constitution](../constitution/platform-constitution.md)

A database “tier” is not a provider size, billing plan, marketing label, or
mutable string alias. The target uses typed service-class Resources so product,
commercial, and physical concerns remain separate.

## Model

- `Database` is the customer Resource and stable logical identity.
- `DatabaseClass` is a versioned customer-visible Resource describing an
  availability, durability, performance, capacity, support, and cost envelope.
- `Entitlement` decides which classes and limits a Principal may use.
- `DatabasePlacement` is restricted observed status owned by the Data plane; it
  is not customer intent and exposes no raw provider topology.
- create, resize, backup, restore, branch, promote, rotate, and delete are
  durable Operations.
- backups, exports, and restore evidence are Artifacts by digest.

## DatabaseClass contract

A class declares typed bounds and guarantees, including:

- intended workload class;
- availability target and failure-domain scope;
- durability, backup frequency, retention, RPO, and RTO;
- minimum/maximum compute, memory, storage, connections, and throughput;
- autoscaling and burst behavior;
- maintenance, upgrade, and support envelope;
- residency and isolation options when admitted;
- estimated and metered cost model; and
- capacity/admission behavior under scarcity.

A class name is stable. A material contract change creates a new class revision
or class; it is not silently changed behind an old name.

## Customer contract

Customers select a `DatabaseClass` reference and product settings. They do not
select:

- provider instance types;
- orchestration identities, internal volumes, placement classes, or operators;
- replication implementation;
- pool density;
- queue or scheduler names; or
- an internal database primary.

Marketing plans may recommend or entitle service classes, but plan names are not
accepted as database class aliases.

## Lifecycle

### Create

Creation accepts a canonical parent, Resource ID, typed database spec, class
reference, revision-safe request ID, and Policy context. It returns one
Operation. `Ready=true` is set only after the declared connection, durability,
security, and customer-path postconditions are observed.

### Resize or class change

A class change is planned before execution and reports:

- compatibility and limit checks;
- expected interruption and maintenance class;
- estimated cost delta;
- capacity-admission result;
- data movement or placement consequences;
- rollback/compensation boundary; and
- required approval for destructive or irreversible transitions.

The logical Database name and `uid` remain stable unless the requested action
explicitly creates a new Database.

### Backup, restore, and branch

- backup produces an immutable Artifact plus typed backup Resource state;
- restore creates a new Database by default;
- in-place restore is a distinct destructive Operation with plan and approval;
- branch creates a new isolated Database with explicit retention and data
  sensitivity;
- every action binds source revision, backup Artifact digest, target class,
  Policy decision, and Evidence.

### Delete

Deletion fences new bindings, applies retention/legal-hold Policy, proves
external deletion or retained state, emits terminal Events and Evidence, and
then tombstones or removes the Resource. “Force” is a separate Operation with
explicit data-loss and orphan semantics.

## Availability and scaling law

Database authorities are partitioned by Resource home and Cell. No global
primary, lock, storage quorum, or synchronous cross-Cell transaction sits in the
general management hot path. A physical technology may have its own local
quorum; that local mechanism never becomes the global Platform authority.

## Verification

Each shipped class requires current evidence for:

- availability and failover under declared failure scope;
- sustained and tail throughput at published limits;
- noisy-neighbor isolation and admission behavior;
- backup integrity, point-in-time recovery, restore, and disaster recovery;
- resize and class-change safety;
- encryption, credential rotation, tenant isolation, and audit;
- metering and invoice reconciliation;
- capacity and cost envelope; and
- real customer create, connect, write, failover, restore, and delete paths.

Legacy `hobby`, `starter`, `pro`, `business`, `enterprise`, size aliases,
`standard` aliases, and `/api/v1/resources` examples are predecessor vocabulary.
They may be mapped once by an executor during the hard cut, but they are not
preserved in the target contract.

## docs/reference/compute-profiles.md

# Compute Capacity Classes

**Status:** Derived target reference; exact commercial packaging and live capacity are discovered at runtime
**Authority:** [Work family](../specs/2026-08-07-capability-family-contracts.md#work), [Commerce and Policy split](north-star-architecture.md#12-identity-policy-and-commerce)

A compute capacity class is a stable product-level execution envelope. It is not
a runner implementation, node type, scheduler queue, provider machine, or
billing plan.

## Contract

Each class declares:

- stable class name and revision;
- CPU, memory, accelerator, architecture, operating-system, isolation, network,
  storage, and maximum-duration envelope;
- workload shapes for which it is eligible;
- expected startup and execution SLO;
- durability and workspace-retention behavior;
- concurrency, fairness, preemption, and overload policy;
- metering unit and cost-estimation inputs;
- admitted product regions and Cells;
- deprecation state and an explicit hard-cut successor when replaced.

The selected physical shape may vary by Cell while satisfying the same measured
contract. Unsupported or ambiguous requests fail typed; they never silently run
on a different class.

## Admission authorities

1. Commerce Entitlement says which classes the customer purchased or may use.
2. Policy `LimitPolicy` says whether this Principal and request may consume the
   class, concurrency, budget, and effect scope.
3. Capacity admission says whether ready physical capacity exists.
4. The workload scheduler selects placement.

These decisions are correlated but never collapsed into one authority. A plan
or price name is not a scheduler label.

## Work integration

`Service`, `BatchJob`, `Workflow`, and `Session` reference a product capacity
class in typed intent. Plan resolves:

- class revision and compatibility with the workload Artifact;
- Entitlement and Policy revisions;
- admitted region/Cell availability;
- concurrency and queue impact;
- estimated cost and maximum bound;
- fallback behavior, which is normally `none` unless a caller explicitly plans
  an equivalent class set with a deterministic selection rule.

Apply returns an Operation. Admission wait, placement, startup, preemption,
execution, usage, cost, and terminal result remain observable without exposing
raw infrastructure.

## Lifecycle

A class replacement is an explicit contract revision or major hard cut.
Old labels, multi-label aliases, beta compatibility mappings are deleted; silent
size substitution is not retained. Discovery reports unavailable or retired classes
as typed state, and new intent uses the admitted successor identity.

Customer workflows and generated clients consume only names published by
current discovery. This reference intentionally contains no fixed plan-to-class
matrix and no claim that a historical label is currently available.

## Evidence

Each shipped class has measured:

- startup, queue, execution, and teardown latency;
- sustained throughput and tail latency under contention;
- tenant isolation and noisy-neighbor behavior;
- process, node, zone, scheduler, image, network, and storage failure behavior;
- overload, fairness, borrowing, and preemption behavior;
- metering accuracy and estimated-versus-actual cost;
- customer-path behavior for every supported workload and operating-system
  profile.

A label in source, a runner registered with a forge, or an idle machine is not
capacity proof. Exact availability comes from generated discovery, admitted
ready capacity, and trusted live readback.