@aeolus-fleet/core 0.0.0 → 0.19.0

package/src/adapters/prisma/schema.prisma

@@ -0,0 +1,558 @@
+// Aeolus core tables (docs/architecture.md, "Core tables").
+//
+// Prefixed ids, fleet_id on every table except fleets, and the columns and key
+// constraints named in the architecture. Columns a later slice owns (a message's
+// sender and selector, for one) arrive with that slice.
+//
+// References to rows of the same fleet carry fleet_id in the foreign key, so a
+// row can never point at another fleet's ship, lease, message or delivery.
+//
+// Timestamps have no database default: the application's Clock port sets every
+// one of them, so tests control time.
+//
+// Check constraints and the append-only rule for events live in the migration
+// SQL, because Prisma does not model them.
+
+generator client {
+  provider            = "prisma-client"
+  output              = "./generated"
+  moduleFormat        = "esm"
+  importFileExtension = "js"
+  runtime             = "nodejs"
+  previewFeatures     = ["partialIndexes"]
+}
+
+datasource db {
+  provider = "postgresql"
+}
+
+/// The tenant: one operator's ships, messages and history. Ids start with flt_.
+model Fleet {
+  id                   String   @id
+  name                 String
+  createdAt            DateTime @map("created_at") @db.Timestamptz(3)
+  /// The sequence number of the fleet's last committed event. A unit of work
+  /// takes its numbers from it as its last statements, so the row lock orders
+  /// the numbers as the transactions commit.
+  lastEventSeq         BigInt   @default(0) @map("last_event_seq")
+  /// Whether the fleet sets its own ship limit (else it follows the installation
+  /// default), and that limit: null for no limit.
+  shipLimitSet         Boolean  @default(false) @map("ship_limit_set")
+  shipLimit            Int?     @map("ship_limit")
+  /// The same for its daily message limit.
+  dailyMessageLimitSet Boolean  @default(false) @map("daily_message_limit_set")
+  dailyMessageLimit    Int?     @map("daily_message_limit")
+
+  ships            Ship[]
+  leases           Lease[]
+  crewRequests     CrewRequest[]
+  credentials      Credential[]
+  messages         Message[]
+  deliveries       Delivery[]
+  events           Event[]
+  consoleSessions  ConsoleSession[]
+  signInTickets    SignInTicket[]
+  noticeDismissals NoticeDismissal[]
+  guideProgress    GuideProgress[]
+  operator         Operator?
+
+  @@map("fleets")
+}
+
+/// `argo` is the one operator ship of a fleet; every other ship is an agent.
+enum ShipKind {
+  operator
+  agent
+  viewer
+
+  @@map("ship_kind")
+}
+
+/// A durable, addressable identity with an inbox. Ids start with shp_.
+/// Scopes are set when the ship is created and checked before every call.
+model Ship {
+  id                    String    @id
+  fleetId               String    @map("fleet_id")
+  name                  String
+  type                  String
+  kind                  ShipKind
+  scopes                String[]
+  note                  String?
+  createdAt             DateTime  @map("created_at") @db.Timestamptz(3)
+  retiredAt             DateTime? @map("retired_at") @db.Timestamptz(3)
+  /// The ship that commissioned it, its idempotency key and the request's hash; null for argo.
+  commissionedBy        String?   @map("commissioned_by")
+  commissionKey         String?   @map("commission_key")
+  commissionRequestHash String?   @map("commission_request_hash")
+
+  fleet             Fleet            @relation(fields: [fleetId], references: [id])
+  leases            Lease[]
+  credentials       Credential[]
+  sentMessages      Message[]        @relation("MessageSender")
+  addressedMessages Message[]        @relation("MessageSelectorShip")
+  deliveries        Delivery[]       @relation("DeliveryRecipientShip")
+  claimedDeliveries Delivery[]       @relation("DeliveryClaimedByShip")
+  consoleSessions   ConsoleSession[]
+  actorOfEvents     Event[]          @relation("EventActorShip")
+  events            Event[]          @relation("EventShip")
+  crewRequest       CrewRequest?     @relation("CrewRequestShip")
+  assignedCrews     CrewRequest[]    @relation("CrewRequestAssignee")
+
+  @@unique([fleetId, id])
+  /// An idempotency key is used once per commissioning ship.
+  @@unique([fleetId, commissionedBy, commissionKey])
+  /// A name is unique among ships that are not retired, and reusable after retirement.
+  @@unique([fleetId, name], map: "ships_fleet_id_name_active_key", where: { retiredAt: null })
+  /// Exactly one operator ship per fleet.
+  @@unique([fleetId], map: "ships_fleet_id_operator_key", where: raw("kind = 'operator'::ship_kind"))
+  /// At most one viewer ship per fleet (decision 0022).
+  @@unique([fleetId], map: "ships_fleet_id_viewer_key", where: raw("kind = 'viewer'::ship_kind"))
+  @@map("ships")
+}
+
+/// Where the session crewing a ship runs. OTHER carries a description; the other kinds none.
+enum ReportState {
+  working
+  blocked
+  idle
+
+  @@map("report_state")
+}
+
+enum LocationKind {
+  DEVICE
+  CLOUD
+  SERVER
+  OTHER
+
+  @@map("location_kind")
+}
+
+/// The exclusive right of one session to crew a ship, and where that session runs.
+/// Ids start with lse_.
+/// The hash of the crew token register gave the session, unique across all fleets:
+/// finding a ship by its crew token is a lookup not scoped by fleet (ADR 0007). A
+/// console session's lease on argo has none; the console session holds its token.
+model Lease {
+  id                   String       @id
+  fleetId              String       @map("fleet_id")
+  shipId               String       @map("ship_id")
+  location             LocationKind
+  locationDescription  String?      @map("location_description")
+  /// The harness the session stated when it claimed the ship; none for argo's console lease and for leases from before harnesses were stated.
+  harness              String?
+  crewTokenHash        String?      @unique @map("crew_token_hash")
+  startedAt            DateTime     @map("started_at") @db.Timestamptz(3)
+  /// The last call by its crew: observation only, nothing acts on it (ADR 0016).
+  lastSeenAt           DateTime?    @map("last_seen_at") @db.Timestamptz(3)
+  /// The crew's last report: plain data, nothing acts on it. Null until it reports.
+  reportState          ReportState? @map("report_state")
+  reportNote           String?      @map("report_note")
+  reportedAt           DateTime?    @map("reported_at") @db.Timestamptz(3)
+  /// The report's details: one JSON object stored without meaning, at most 16 KB (decision 0028). Null when there are none.
+  reportDetails        Json?        @map("report_details")
+  /// Moves by one each time the details change; 0 before any.
+  reportDetailsVersion Int          @default(0) @map("report_details_version")
+  endedAt              DateTime?    @map("ended_at") @db.Timestamptz(3)
+
+  fleet             Fleet            @relation(fields: [fleetId], references: [id])
+  ship              Ship             @relation(fields: [fleetId, shipId], references: [fleetId, id])
+  consoleSessions   ConsoleSession[]
+  claimedDeliveries Delivery[]
+
+  @@unique([fleetId, id])
+  /// At most one open lease per ship.
+  @@unique([shipId], map: "leases_ship_id_open_key", where: { endedAt: null })
+  @@map("leases")
+}
+
+/// How the assigned trierarch says its crew of a ship stands (decision 0029).
+enum CrewStatus {
+  crewing
+  running
+  restarting
+  crashed
+  releasing
+
+  @@map("crew_status")
+}
+
+/// A standing request that a ship be kept crewed (decision 0029): at most one per
+/// ship, so the ship's id is its key. Its settings are stored without meaning, at
+/// most 16 KB; each request replaces them and moves their version by one.
+model CrewRequest {
+  shipId          String      @id @map("ship_id")
+  fleetId         String      @map("fleet_id")
+  settings        Json
+  settingsVersion Int         @map("settings_version")
+  requestedAt     DateTime    @map("requested_at") @db.Timestamptz(3)
+  /// The trierarch ship it is assigned to; null while unassigned.
+  assignedTo      String?     @map("assigned_to_ship_id")
+  /// How its trierarch says the crew stands; null until it says.
+  status          CrewStatus?
+  /// Why no trierarch can take it, written by the assigner while unassigned; null when none.
+  reason          String?
+
+  fleet    Fleet @relation(fields: [fleetId], references: [id])
+  ship     Ship  @relation("CrewRequestShip", fields: [fleetId, shipId], references: [fleetId, id])
+  assignee Ship? @relation("CrewRequestAssignee", fields: [fleetId, assignedTo], references: [fleetId, id])
+
+  @@unique([fleetId, shipId])
+  /// A trierarch reads the requests assigned to it.
+  @@index([fleetId, assignedTo])
+  @@map("crew_requests")
+}
+
+/// A ship secret, stored only as its hash. Ids start with crd_.
+/// The hash is unique across all fleets: finding a ship by its secret is one of the
+/// lookups not scoped by fleet (ADR 0007).
+model Credential {
+  id            String    @id
+  fleetId       String    @map("fleet_id")
+  shipId        String    @map("ship_id")
+  secretHash    String    @unique @map("secret_hash")
+  issuedAt      DateTime  @map("issued_at") @db.Timestamptz(3)
+  claimedAt     DateTime? @map("claimed_at") @db.Timestamptz(3)
+  invalidatedAt DateTime? @map("invalidated_at") @db.Timestamptz(3)
+
+  fleet Fleet @relation(fields: [fleetId], references: [id])
+  ship  Ship  @relation(fields: [fleetId, shipId], references: [fleetId, id])
+
+  /// At most one valid secret per ship.
+  @@unique([shipId], map: "credentials_ship_id_valid_key", where: { invalidatedAt: null })
+  @@map("credentials")
+}
+
+/// Who a message is for: one ship or any ship of a type. Group and fleet come later.
+enum SelectorKind {
+  ship
+  type
+
+  @@map("selector_kind")
+}
+
+/// An immutable envelope plus an opaque payload of at most 64 KB, sent by one ship.
+/// Ids start with msg_. The selector is stored as resolved at send time: a ship's
+/// id, never its name, or a type. It can name the message it replies to, and a
+/// resend names the message it resends (nothing sets that yet).
+model Message {
+  id                 String       @id
+  fleetId            String       @map("fleet_id")
+  senderShipId       String       @map("sender_ship_id")
+  selectorKind       SelectorKind @map("selector_kind")
+  selectorShipId     String?      @map("selector_ship_id")
+  selectorType       String?      @map("selector_type")
+  payload            String
+  contentType        String       @map("content_type")
+  /// The model the sender's session stated; none from argo and on messages from before models were stated.
+  model              String?
+  idempotencyKey     String       @map("idempotency_key")
+  requestHash        String       @map("request_hash")
+  inReplyToMessageId String?      @map("in_reply_to_message_id")
+  resendOfMessageId  String?      @map("resend_of_message_id")
+  createdAt          DateTime     @map("created_at") @db.Timestamptz(3)
+
+  fleet        Fleet      @relation(fields: [fleetId], references: [id])
+  senderShip   Ship       @relation("MessageSender", fields: [fleetId, senderShipId], references: [fleetId, id], onDelete: Restrict)
+  selectorShip Ship?      @relation("MessageSelectorShip", fields: [fleetId, selectorShipId], references: [fleetId, id], onDelete: Restrict)
+  inReplyTo    Message?   @relation("MessageInReplyTo", fields: [fleetId, inReplyToMessageId], references: [fleetId, id], onDelete: Restrict)
+  replies      Message[]  @relation("MessageInReplyTo")
+  resendOf     Message?   @relation("MessageResendOf", fields: [fleetId, resendOfMessageId], references: [fleetId, id], onDelete: Restrict)
+  resends      Message[]  @relation("MessageResendOf")
+  deliveries   Delivery[]
+  events       Event[]
+
+  @@unique([fleetId, id])
+  /// A sender uses an idempotency key once: a repeat of the same request, told by its
+  /// request hash, returns the original message; another request with the key is refused.
+  @@unique([fleetId, senderShipId, idempotencyKey])
+  /// A ship's current model is its newest message with a model.
+  @@index([fleetId, senderShipId, createdAt])
+  @@map("messages")
+}
+
+enum DeliveryState {
+  pending
+  delivered
+  acknowledged
+  undeliverable
+  dismissed
+  abandoned
+
+  @@map("delivery_state")
+}
+
+/// One message to one resolved recipient: a ship or a type. Ids start with dlv_.
+/// A receive claims it for the ship and the lease of the crew receiving: set while it
+/// is in flight, kept once acknowledged, none while it is pending. Attempts count the
+/// claims; the fifth makes it undeliverable.
+/// The read date is set when the operator opens a message to argo.
+model Delivery {
+  id               String        @id
+  fleetId          String        @map("fleet_id")
+  messageId        String        @map("message_id")
+  recipientShipId  String?       @map("recipient_ship_id")
+  recipientType    String?       @map("recipient_type")
+  state            DeliveryState @default(pending)
+  claimedByShipId  String?       @map("claimed_by_ship_id")
+  claimedByLeaseId String?       @map("claimed_by_lease_id")
+  attempts         Int           @default(0)
+  readAt           DateTime?     @map("read_at") @db.Timestamptz(3)
+  createdAt        DateTime      @map("created_at") @db.Timestamptz(3)
+
+  fleet          Fleet   @relation(fields: [fleetId], references: [id])
+  message        Message @relation(fields: [fleetId, messageId], references: [fleetId, id])
+  recipientShip  Ship?   @relation("DeliveryRecipientShip", fields: [fleetId, recipientShipId], references: [fleetId, id], onDelete: Restrict)
+  claimedByShip  Ship?   @relation("DeliveryClaimedByShip", fields: [fleetId, claimedByShipId], references: [fleetId, id], onDelete: Restrict)
+  claimedByLease Lease?  @relation(fields: [fleetId, claimedByLeaseId], references: [fleetId, id], onDelete: Restrict)
+  events         Event[]
+
+  @@unique([fleetId, id])
+  /// One row per recipient.
+  @@unique([messageId, recipientShipId])
+  @@unique([messageId, recipientType])
+  @@index([fleetId, recipientShipId, state])
+  @@index([fleetId, recipientType, state])
+  /// A crew's own deliveries in flight, which its next receive returns first.
+  @@index([fleetId, claimedByLeaseId, state])
+  @@map("deliveries")
+}
+
+/// Append-only log of every state change: never updated or deleted. Ids start with evt_.
+/// Records its type and time, who caused it (a ship, or the system when
+/// actor_ship_id is null), the ship, message and delivery it concerns, and a few
+/// details as a flat JSON object.
+model Event {
+  id          String   @id
+  fleetId     String   @map("fleet_id")
+  type        String
+  occurredAt  DateTime @map("occurred_at") @db.Timestamptz(3)
+  actorShipId String?  @map("actor_ship_id")
+  shipId      String?  @map("ship_id")
+  messageId   String?  @map("message_id")
+  deliveryId  String?  @map("delivery_id")
+  details     Json
+  /// The event's place in its fleet's stream, in commit order and without
+  /// gaps: where a live subscription resumes. The id is not, since ids are
+  /// taken before their transaction commits.
+  seq         BigInt
+
+  fleet     Fleet     @relation(fields: [fleetId], references: [id])
+  actorShip Ship?     @relation("EventActorShip", fields: [fleetId, actorShipId], references: [fleetId, id], onDelete: Restrict)
+  ship      Ship?     @relation("EventShip", fields: [fleetId, shipId], references: [fleetId, id], onDelete: Restrict)
+  message   Message?  @relation(fields: [fleetId, messageId], references: [fleetId, id], onDelete: Restrict)
+  delivery  Delivery? @relation(fields: [fleetId, deliveryId], references: [fleetId, id], onDelete: Restrict)
+
+  @@unique([fleetId, seq])
+  @@map("events")
+}
+
+/// Why a console session ended: a sign-in elsewhere took argo over, the
+/// operator signed out, or the password was reset.
+enum ConsoleSessionEndReason {
+  takenOver
+  signedOut
+  passwordReset
+
+  @@map("console_session_end_reason")
+}
+
+/// The operator's login: email and Argon2id password hash, none for an operator a
+/// hosting installation created. Ids start with opr_.
+/// The email is unique across all fleets: finding the account by email is the one
+/// lookup not scoped by fleet (ADR 0007). One account per fleet in v1.
+model Operator {
+  id           String   @id
+  fleetId      String   @unique @map("fleet_id")
+  email        String   @unique
+  passwordHash String?  @map("password_hash")
+  /// How the console looks for this operator; system until they choose.
+  theme        Theme    @default(system)
+  createdAt    DateTime @map("created_at") @db.Timestamptz(3)
+
+  fleet Fleet @relation(fields: [fleetId], references: [id])
+
+  @@map("operators")
+}
+
+enum Theme {
+  light
+  dark
+  system
+
+  @@map("theme")
+}
+
+/// The operator crewing argo through the web console. Ids start with ses_.
+/// Only the hash of the session token is stored, unique across all fleets: finding
+/// a session by its token is the one lookup not scoped by fleet (ADR 0007).
+/// Valid until expires_at, which moves to idle_limit_seconds after each use
+/// (30 days for the operator, 2 hours for a viewer), never past ends_by.
+model ConsoleSession {
+  id               String                   @id
+  fleetId          String                   @map("fleet_id")
+  shipId           String                   @map("ship_id")
+  /// The lease on argo it holds; null for a viewer session (decision 0022).
+  leaseId          String?                  @map("lease_id")
+  idleLimitSeconds Int                      @map("idle_limit_seconds")
+  /// No use renews it past this; null when only idleness ends it.
+  endsBy           DateTime?                @map("ends_by") @db.Timestamptz(3)
+  /// The device it signed in from, as the browser told: "Mac · Chrome".
+  device           String                   @default("Unknown device")
+  tokenHash        String                   @unique @map("token_hash")
+  createdAt        DateTime                 @map("created_at") @db.Timestamptz(3)
+  lastUsedAt       DateTime                 @map("last_used_at") @db.Timestamptz(3)
+  expiresAt        DateTime                 @map("expires_at") @db.Timestamptz(3)
+  endedAt          DateTime?                @map("ended_at") @db.Timestamptz(3)
+  /// Why the session ended; null while it has not.
+  endReason        ConsoleSessionEndReason? @map("end_reason")
+
+  fleet Fleet  @relation(fields: [fleetId], references: [id])
+  ship  Ship   @relation(fields: [fleetId, shipId], references: [fleetId, id])
+  lease Lease? @relation(fields: [fleetId, leaseId], references: [fleetId, id])
+
+  noticeDismissals NoticeDismissal[]
+  guideProgress    GuideProgress[]
+
+  /// At most one live session holding argo's lease per fleet: signing in ends the previous one. Viewer sessions run beside it.
+  @@unique([fleetId], map: "console_sessions_fleet_id_open_key", where: raw("ended_at IS NULL AND lease_id IS NOT NULL"))
+  @@map("console_sessions")
+}
+
+/// A one-time sign-in ticket for the fleet's operator, issued by a hosting
+/// installation and redeemed in the console (decision 0020). Only its hash is
+/// stored, unique across all fleets: redeeming finds it before the fleet is known.
+model SignInTicket {
+  tokenHash String    @id @map("token_hash")
+  fleetId   String    @map("fleet_id")
+  /// Whom it signs in as: the operator or a viewer (decision 0022).
+  signInAs  SignInAs  @map("sign_in_as")
+  issuedAt  DateTime  @map("issued_at") @db.Timestamptz(3)
+  expiresAt DateTime  @map("expires_at") @db.Timestamptz(3)
+  /// When it signed in; null while unused.
+  usedAt    DateTime? @map("used_at") @db.Timestamptz(3)
+
+  fleet Fleet @relation(fields: [fleetId], references: [id])
+
+  @@index([fleetId])
+  @@map("sign_in_tickets")
+}
+
+enum SignInAs {
+  operator
+  viewer
+
+  @@map("sign_in_as")
+}
+
+/// The installation's settings (decision 0020): the default ship and daily message
+/// limits for fleets and the cap on fleets, each null for no limit. One row at most,
+/// and none until the installation sets them. Belongs to no fleet.
+model InstallationSettings {
+  id                       Int  @id @default(1)
+  defaultShipLimit         Int? @map("default_ship_limit")
+  defaultDailyMessageLimit Int? @map("default_daily_message_limit")
+  fleetCap                 Int? @map("fleet_cap")
+
+  @@map("installation_settings")
+}
+
+enum InstallationRequestKind {
+  createFleet @map("create_fleet")
+  deleteFleet @map("delete_fleet")
+
+  @@map("installation_request_kind")
+}
+
+/// A create or delete of a fleet the installation carried out, under its caller's
+/// request id, so a replay answers the same (decision 0020). It belongs to the
+/// installation, not to a fleet, and keeps the request as a hash only. A create's
+/// row names the fleet and argo it answers with and is deleted with that fleet; a
+/// delete's row names nothing of the fleet.
+model InstallationRequest {
+  requestId      String                  @id @map("request_id")
+  kind           InstallationRequestKind
+  requestHash    String                  @map("request_hash")
+  /// The created fleet and its argo; null for a delete.
+  fleetId        String?                 @map("fleet_id")
+  operatorShipId String?                 @map("operator_ship_id")
+  at             DateTime                @db.Timestamptz(3)
+
+  @@index([fleetId])
+  @@map("installation_requests")
+}
+
+/// A console notice the installation sets (decision 0023), shown above every
+/// page to the sessions of its audience. It belongs to no fleet.
+model Notice {
+  id            String         @id
+  /// Its place in the installation's order.
+  position      Int
+  audience      NoticeAudience
+  text          String
+  /// Its links: label, and url, isSignOut or both.
+  links         Json           @default("[]")
+  isDismissible Boolean        @default(false) @map("is_dismissible")
+
+  @@map("notices")
+}
+
+enum NoticeAudience {
+  everyone
+  operators
+  viewers
+
+  @@map("notice_audience")
+}
+
+/// A notice a console session dismissed, for itself (decision 0023). It goes
+/// with its session and its fleet.
+model NoticeDismissal {
+  fleetId          String   @map("fleet_id")
+  consoleSessionId String   @map("console_session_id")
+  noticeId         String   @map("notice_id")
+  dismissedAt      DateTime @map("dismissed_at") @db.Timestamptz(3)
+
+  fleet          Fleet          @relation(fields: [fleetId], references: [id])
+  consoleSession ConsoleSession @relation(fields: [consoleSessionId], references: [id])
+
+  @@id([consoleSessionId, noticeId])
+  @@index([fleetId])
+  @@map("notice_dismissals")
+}
+
+/// The installation's guide (decision 0024): steps for the console sessions of
+/// one audience. At most one row; it belongs to no fleet.
+model Guide {
+  /// Always "guide": the installation has one guide or none.
+  id       String         @id
+  audience NoticeAudience
+  /// Its steps, in order: path, anchor (optional), title and text.
+  steps    Json
+
+  @@map("guides")
+}
+
+enum GuideProgressState {
+  open
+  skipped
+  finished
+
+  @@map("guide_progress_state")
+}
+
+/// Where a console session is in the guide, for itself (decision 0024). It
+/// goes with its session and its fleet.
+model GuideProgress {
+  fleetId          String             @map("fleet_id")
+  consoleSessionId String             @id @map("console_session_id")
+  step             Int
+  state            GuideProgressState
+  recordedAt       DateTime           @map("recorded_at") @db.Timestamptz(3)
+
+  fleet          Fleet          @relation(fields: [fleetId], references: [id])
+  consoleSession ConsoleSession @relation(fields: [consoleSessionId], references: [id])
+
+  @@index([fleetId])
+  @@map("guide_progress")
+}