@odoro-cli/fleet-protocol 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,424 @@
+import { z } from 'zod';
+
+/**
+ * Ce qu'un agent repond quand il n'a pas fait ce qu'on lui demandait.
+ *
+ * ## Le champ qui compte
+ *
+ * `resourceMayExist` n'est pas un detail de journalisation : c'est lui qui
+ * decide de la suite. Une temporisation ne dit pas que rien n'a ete cree, elle
+ * dit que **nous ne savons pas**. Traiter ce cas comme un echec net conduit a
+ * recreer une ressource qui tourne deja ; le traiter comme un succes conduit a
+ * abandonner une ressource que plus rien ne designe.
+ *
+ * L'agent est le seul a pouvoir renseigner ce champ honnetement : lui seul sait
+ * ou il en etait quand il a echoue.
+ *
+ * ## Pourquoi le protocole est plus riche que le port
+ *
+ * Le port du plan de controle connait sept sortes d'echecs, et c'est
+ * volontairement peu : y ajouter des cas propres a un fournisseur ferait fuiter
+ * l'amont dans la logique metier.
+ *
+ * Mais l'agent, lui, a des refus qui portent une information qu'on perdrait a
+ * la reduire. Une suppression refusee parce que des branches en dependent n'est
+ * pas un conflit anonyme : c'est un conflit **avec une liste de noms**, et
+ * cette liste est ce qui permet a un humain de decider.
+ *
+ * Le protocole transporte donc le detail, et l'adaptateur le replie dans le
+ * message de l'erreur du port. Rien n'est perdu, et le port ne grossit pas.
+ *
+ * @module
+ */
+
+/**
+ * Les sortes d'echecs, alignees sur le port du plan de controle.
+ *
+ * Aucune n'est ajoutee ici : un agent qui inventerait une categorie forcerait
+ * l'adaptateur a la traduire en `malformed`, ce qui est pire que de choisir la
+ * bonne des sept.
+ */
+declare const failureKind: z.ZodEnum<{
+    timeout: "timeout";
+    quota: "quota";
+    conflict: "conflict";
+    unauthorized: "unauthorized";
+    "not-found": "not-found";
+    malformed: "malformed";
+    unavailable: "unavailable";
+}>;
+/** Une sorte d'echec. */
+type FailureKind = z.infer<typeof failureKind>;
+/**
+ * Ce qui accompagne un refus, quand le refus a une raison nommable.
+ *
+ * Chaque variante existe parce qu'un message libre aurait force le lecteur a
+ * l'analyser pour agir. Ici, l'adaptateur decide sur la forme.
+ */
+declare const failureDetail: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    reason: z.ZodLiteral<"branches-dependantes">;
+    branches: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    reason: z.ZodLiteral<"base-endormie">;
+    ref: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    reason: z.ZodLiteral<"place-insuffisante">;
+    requiredBytes: z.ZodNumber;
+    availableBytes: z.ZodNumber;
+}, z.core.$strip>], "reason">;
+/** Ce qui accompagne un refus. */
+type FailureDetail = z.infer<typeof failureDetail>;
+/**
+ * Le corps d'une reponse en echec.
+ *
+ * Il ne contient jamais de chaine de connexion ni de mot de passe : une erreur
+ * est ce qui finit le plus surement dans un journal, un rapport d'incident ou
+ * un ticket.
+ */
+declare const failureBody: z.ZodObject<{
+    kind: z.ZodEnum<{
+        timeout: "timeout";
+        quota: "quota";
+        conflict: "conflict";
+        unauthorized: "unauthorized";
+        "not-found": "not-found";
+        malformed: "malformed";
+        unavailable: "unavailable";
+    }>;
+    message: z.ZodString;
+    resourceMayExist: z.ZodBoolean;
+    detail: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        reason: z.ZodLiteral<"branches-dependantes">;
+        branches: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        reason: z.ZodLiteral<"base-endormie">;
+        ref: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        reason: z.ZodLiteral<"place-insuffisante">;
+        requiredBytes: z.ZodNumber;
+        availableBytes: z.ZodNumber;
+    }, z.core.$strip>], "reason">>;
+    requestId: z.ZodString;
+}, z.core.$strip>;
+/** Le corps d'une reponse en echec. */
+type FailureBody = z.infer<typeof failureBody>;
+/**
+ * Le code HTTP qui accompagne chaque sorte.
+ *
+ * ## Pourquoi cette table plutot qu'un code par cas
+ *
+ * L'appelant decide sur `kind`, pas sur le code : c'est le corps qui porte le
+ * sens. Le code existe pour les intermediaires — relais, journaux, sondes — qui
+ * ne lisent pas le corps et pour qui la difference entre 4xx et 5xx decide de
+ * reessayer ou non.
+ *
+ * `timeout` vaut 504 et non 408 : 408 dit que le **client** a ete trop lent, ce
+ * qui designerait le mauvais coupable dans tous les journaux qui le liront.
+ */
+declare const STATUS_BY_KIND: Readonly<Record<FailureKind, number>>;
+/**
+ * Une sorte d'echec merite-t-elle d'etre reessayee telle quelle ?
+ *
+ * Exposee ici plutot que decidee chez l'appelant : deux appelants qui en
+ * jugeraient differemment produiraient deux comportements pour une meme panne,
+ * et le second serait decouvert un jour d'incident.
+ *
+ * `conflict` est absent a dessein. Reessayer un conflit produit le meme
+ * conflit — sauf quand il vient d'un doublon en vol, et ce cas se resout par la
+ * cle d'idempotence, pas par un reessai.
+ */
+declare function isRetryable(kind: FailureKind): boolean;
+/**
+ * Rend le refus lisible par un humain, detail compris.
+ *
+ * Un refus dont la raison reste dans un champ structure est un refus que
+ * personne ne lit : c'est le message qui arrive dans le ticket.
+ */
+declare function describeFailure(body: FailureBody): string;
+
+/**
+ * Les neuf operations d'un agent de flotte.
+ *
+ * ## Elles ne sont pas inventees ici
+ *
+ * Elles repondent une pour une au port du plan de controle. C'est une
+ * contrainte volontaire : une operation de plus ici serait une operation que le
+ * plan de controle ne sait pas appeler, donc du code mort qui aurait l'air
+ * vivant.
+ *
+ * ## La region est une chaine libre, et c'est delibere
+ *
+ * Le plan de controle a son propre vocabulaire de regions, qui decrit une offre
+ * commerciale. Un agent, lui, connait la machine sur laquelle il tourne. Les
+ * deux ne coincident pas forcement, et les faire coincider par contrat
+ * obligerait a modifier la flotte chaque fois que l'offre change.
+ *
+ * L'agent rend donc la region telle qu'il la connait, et **l'adaptateur la
+ * traduit**. Une region qu'il ne sait pas traduire est un `malformed` — un
+ * echec nomme, decouvert au premier appel, et non une valeur fausse qui se
+ * propage.
+ *
+ * @module
+ */
+
+/** Une reference de ressource, telle que l'agent la fabrique. */
+declare const resourceRef: z.ZodString;
+/**
+ * Le nom demande, qui encode l'identifiant du plan de controle.
+ *
+ * L'agent ne le decode pas et n'a pas a le comprendre : il le stocke et le
+ * rend. C'est la reconciliation, en haut, qui en tire l'identifiant — et elle
+ * seule connait la regle.
+ */
+declare const resourceName: z.ZodString;
+/**
+ * Une cle d'idempotence, fabriquee par l'appelant avant tout appel.
+ *
+ * Elle est obligatoire sur ce qui cree. Sans elle, un reessai apres
+ * temporisation produit une seconde ressource, et c'est exactement le cas que
+ * `resourceMayExist` existe pour signaler.
+ */
+declare const idempotencyKey: z.ZodString;
+/** Ce qu'une creation rend. */
+declare const provisioned: z.ZodObject<{
+    ref: z.ZodString;
+    connectionString: z.ZodString;
+    region: z.ZodString;
+}, z.core.$strip>;
+/** Ce qu'une creation rend. */
+type Provisioned = z.infer<typeof provisioned>;
+/** Ce que l'agent sait d'une ressource qu'il heberge. */
+declare const hostedResource: z.ZodObject<{
+    ref: z.ZodString;
+    name: z.ZodString;
+    available: z.ZodBoolean;
+    region: z.ZodString;
+    sleeping: z.ZodBoolean;
+    parentRef: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Ce que l'agent sait d'une ressource qu'il heberge. */
+type HostedResource = z.infer<typeof hostedResource>;
+/**
+ * La consommation, relevee et jamais estimee.
+ *
+ * Le plan de controle refuse de provisionner quand la derniere mesure est
+ * perimee. Cette regle ne protege de rien si la mesure est un calcul : elle
+ * rendrait un chiffre frais et faux, ce qui est pire qu'un chiffre absent.
+ */
+declare const measuredUsage: z.ZodObject<{
+    ref: z.ZodString;
+    storageBytes: z.ZodNumber;
+    computeSeconds: z.ZodNumber;
+    from: z.ZodISODateTime;
+    to: z.ZodISODateTime;
+    measuredAt: z.ZodISODateTime;
+}, z.core.$strip>;
+/** La consommation relevee. */
+type MeasuredUsage = z.infer<typeof measuredUsage>;
+/** Ce que l'agent dit de lui-meme. */
+declare const agentHealth: z.ZodObject<{
+    nodeId: z.ZodString;
+    serving: z.ZodBoolean;
+    hosted: z.ZodNumber;
+    availableBytes: z.ZodNumber;
+    startedAt: z.ZodISODateTime;
+    version: z.ZodString;
+}, z.core.$strip>;
+/** Ce que l'agent dit de lui-meme. */
+type AgentHealth = z.infer<typeof agentHealth>;
+/** Le corps attendu pour creer une base. */
+declare const createDatabaseRequest: z.ZodObject<{
+    name: z.ZodString;
+    region: z.ZodString;
+    idempotencyKey: z.ZodString;
+}, z.core.$strip>;
+/** Le corps attendu pour brancher une base existante. */
+declare const createBranchRequest: z.ZodObject<{
+    name: z.ZodString;
+    parentRef: z.ZodString;
+    idempotencyKey: z.ZodString;
+}, z.core.$strip>;
+/** Une operation du contrat. */
+interface FleetOperation {
+    /** Le nom qu'emploient l'adaptateur et les journaux. */
+    readonly id: string;
+    readonly method: 'GET' | 'POST' | 'DELETE';
+    /** Le chemin, avec `:ref` la ou une reference est attendue. */
+    readonly path: string;
+    /** Le corps attendu, ou `undefined` quand il n'y en a pas. */
+    readonly request: z.ZodType | undefined;
+    /** Le corps rendu en cas de succes. */
+    readonly response: z.ZodType;
+    /**
+     * L'operation modifie-t-elle quelque chose ?
+     *
+     * Sert au relais et aux journaux : une lecture qui echoue se reessaie sans
+     * precaution, une ecriture non.
+     */
+    readonly mutating: boolean;
+}
+/**
+ * Le contrat, en entier.
+ *
+ * `as const satisfies` et non une annotation de type : une annotation
+ * effacerait les schemas au profit de `ZodType`, et tout ce qu'on en
+ * inferrait ensuite deviendrait `unknown` — silencieusement, en compilant.
+ */
+declare const OPERATIONS: readonly [{
+    readonly id: "createDatabase";
+    readonly method: "POST";
+    readonly path: "/v1/databases";
+    readonly request: z.ZodObject<{
+        name: z.ZodString;
+        region: z.ZodString;
+        idempotencyKey: z.ZodString;
+    }, z.core.$strip>;
+    readonly response: z.ZodObject<{
+        ref: z.ZodString;
+        connectionString: z.ZodString;
+        region: z.ZodString;
+    }, z.core.$strip>;
+    readonly mutating: true;
+}, {
+    readonly id: "createBranch";
+    readonly method: "POST";
+    readonly path: "/v1/databases/:ref/branches";
+    readonly request: z.ZodObject<{
+        name: z.ZodString;
+        parentRef: z.ZodString;
+        idempotencyKey: z.ZodString;
+    }, z.core.$strip>;
+    readonly response: z.ZodObject<{
+        ref: z.ZodString;
+        connectionString: z.ZodString;
+        region: z.ZodString;
+    }, z.core.$strip>;
+    readonly mutating: true;
+}, {
+    readonly id: "deleteDatabase";
+    readonly method: "DELETE";
+    readonly path: "/v1/databases/:ref";
+    readonly request: undefined;
+    readonly response: z.ZodObject<{
+        deleted: z.ZodLiteral<true>;
+    }, z.core.$strip>;
+    readonly mutating: true;
+}, {
+    readonly id: "suspend";
+    readonly method: "POST";
+    readonly path: "/v1/databases/:ref/suspend";
+    readonly request: undefined;
+    readonly response: z.ZodObject<{
+        sleeping: z.ZodLiteral<true>;
+    }, z.core.$strip>;
+    readonly mutating: true;
+}, {
+    readonly id: "resume";
+    readonly method: "POST";
+    readonly path: "/v1/databases/:ref/resume";
+    readonly request: undefined;
+    readonly response: z.ZodObject<{
+        sleeping: z.ZodLiteral<false>;
+    }, z.core.$strip>;
+    readonly mutating: true;
+}, {
+    readonly id: "list";
+    readonly method: "GET";
+    readonly path: "/v1/databases";
+    readonly request: undefined;
+    readonly response: z.ZodObject<{
+        resources: z.ZodArray<z.ZodObject<{
+            ref: z.ZodString;
+            name: z.ZodString;
+            available: z.ZodBoolean;
+            region: z.ZodString;
+            sleeping: z.ZodBoolean;
+            parentRef: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    readonly mutating: false;
+}, {
+    readonly id: "rotateCredentials";
+    readonly method: "POST";
+    readonly path: "/v1/databases/:ref/credentials";
+    readonly request: undefined;
+    readonly response: z.ZodObject<{
+        connectionString: z.ZodString;
+    }, z.core.$strip>;
+    readonly mutating: true;
+}, {
+    readonly id: "usage";
+    readonly method: "GET";
+    readonly path: "/v1/databases/:ref/usage";
+    readonly request: undefined;
+    readonly response: z.ZodObject<{
+        ref: z.ZodString;
+        storageBytes: z.ZodNumber;
+        computeSeconds: z.ZodNumber;
+        from: z.ZodISODateTime;
+        to: z.ZodISODateTime;
+        measuredAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+    readonly mutating: false;
+}, {
+    readonly id: "health";
+    readonly method: "GET";
+    readonly path: "/v1/health";
+    readonly request: undefined;
+    readonly response: z.ZodObject<{
+        nodeId: z.ZodString;
+        serving: z.ZodBoolean;
+        hosted: z.ZodNumber;
+        availableBytes: z.ZodNumber;
+        startedAt: z.ZodISODateTime;
+        version: z.ZodString;
+    }, z.core.$strip>;
+    readonly mutating: false;
+}];
+/** L'identifiant d'une operation du contrat. */
+type OperationId = (typeof OPERATIONS)[number]['id'];
+/** Le corps rendu en echec, quelle que soit l'operation. */
+declare const errorResponse: z.ZodObject<{
+    kind: z.ZodEnum<{
+        timeout: "timeout";
+        quota: "quota";
+        conflict: "conflict";
+        unauthorized: "unauthorized";
+        "not-found": "not-found";
+        malformed: "malformed";
+        unavailable: "unavailable";
+    }>;
+    message: z.ZodString;
+    resourceMayExist: z.ZodBoolean;
+    detail: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        reason: z.ZodLiteral<"branches-dependantes">;
+        branches: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        reason: z.ZodLiteral<"base-endormie">;
+        ref: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        reason: z.ZodLiteral<"place-insuffisante">;
+        requiredBytes: z.ZodNumber;
+        availableBytes: z.ZodNumber;
+    }, z.core.$strip>], "reason">>;
+    requestId: z.ZodString;
+}, z.core.$strip>;
+/** Retrouve une operation par son identifiant. */
+declare function operation(id: OperationId): FleetOperation;
+/**
+ * Remplace `:ref` dans un chemin.
+ *
+ * L'encodage n'est pas une precaution de style : une reference contient ce que
+ * l'agent y met, et un caractere non encode changerait le chemin appele.
+ */
+declare function pathFor(op: FleetOperation, ref?: string): string;
+/**
+ * Les operations qui exigent une cle d'idempotence.
+ *
+ * Derivee du contrat plutot qu'ecrite a la main : une liste recopiee finit par
+ * diverger de ce qu'elle decrit, et la divergence se decouvre le jour ou un
+ * reessai cree une seconde base.
+ */
+declare const IDEMPOTENT_OPERATIONS: readonly OperationId[];
+
+export { type AgentHealth, type FailureBody, type FailureDetail, type FailureKind, type FleetOperation, type HostedResource, IDEMPOTENT_OPERATIONS, type MeasuredUsage, OPERATIONS, type OperationId, type Provisioned, STATUS_BY_KIND, agentHealth, createBranchRequest, createDatabaseRequest, describeFailure, errorResponse, failureBody, failureDetail, failureKind, hostedResource, idempotencyKey, isRetryable, measuredUsage, operation, pathFor, provisioned, resourceName, resourceRef };

package/dist/index.js

@@ -0,0 +1,299 @@
+// src/errors.ts
+import { z } from "zod";
+var failureKind = z.enum([
+  /** L'agent n'a pas repondu a temps. La ressource existe peut-etre. */
+  "timeout",
+  /** Plus de place sur la machine, ou quota de la flotte atteint. */
+  "quota",
+  /** Le nom demande est deja pris, ou l'operation heurte un etat existant. */
+  "conflict",
+  /** Jeton absent, expire ou refuse. */
+  "unauthorized",
+  /** L'agent ne connait pas cette ressource. */
+  "not-found",
+  /** La requete est recevable mais son contenu est inexploitable. */
+  "malformed",
+  /** L'agent est la, mais hors d'etat de servir. */
+  "unavailable"
+]);
+var failureDetail = z.discriminatedUnion("reason", [
+  /**
+   * Une suppression refusee parce que des branches vivent sur cette base.
+   *
+   * Un clone depend de l'instantane dont il est issu : detruire le parent
+   * detruirait ses branches. Le refus nomme donc ce qui bloque, sans quoi la
+   * personne qui le lit ne sait ni ce qui s'oppose, ni par ou commencer.
+   */
+  z.object({
+    reason: z.literal("branches-dependantes"),
+    /** Les references des branches qui empechent la suppression. */
+    branches: z.array(z.string().min(1)).min(1)
+  }),
+  /**
+   * Une operation demandee sur une base endormie qui exige qu'elle tourne.
+   *
+   * Distingue d'un `unavailable` : la base va parfaitement bien, elle dort.
+   * L'appelant peut la reveiller et reessayer, ce qu'aucune panne ne permet.
+   */
+  z.object({
+    reason: z.literal("base-endormie"),
+    ref: z.string().min(1)
+  }),
+  /**
+   * La machine n'a plus assez de place.
+   *
+   * Les octets sont donnes parce que « plus de place » ne dit pas s'il manque
+   * un gigaoctet ou un teraoctet, et que la reponse change la decision.
+   */
+  z.object({
+    reason: z.literal("place-insuffisante"),
+    requiredBytes: z.number().int().nonnegative(),
+    availableBytes: z.number().int().nonnegative()
+  })
+]);
+var failureBody = z.object({
+  kind: failureKind,
+  /** Une phrase pour un humain. Jamais analysee par du code. */
+  message: z.string().min(1),
+  /**
+   * L'agent a-t-il pu laisser quelque chose derriere lui ?
+   *
+   * Renseigne par l'agent, jamais devine par l'appelant.
+   */
+  resourceMayExist: z.boolean(),
+  /** Le detail structure, quand le refus en a un. */
+  detail: failureDetail.optional(),
+  /**
+   * L'identifiant de la requete, tel que l'agent l'a journalise.
+   *
+   * C'est ce qui permet de retrouver la trace cote agent a partir d'un rapport
+   * cote plan de controle. Sans lui, les deux journaux ne se rejoignent pas.
+   */
+  requestId: z.string().min(1)
+});
+var STATUS_BY_KIND = {
+  timeout: 504,
+  quota: 507,
+  conflict: 409,
+  unauthorized: 401,
+  "not-found": 404,
+  malformed: 422,
+  unavailable: 503
+};
+function isRetryable(kind) {
+  return kind === "timeout" || kind === "unavailable";
+}
+function describeFailure(body) {
+  const detail = body.detail;
+  if (detail === void 0) return body.message;
+  switch (detail.reason) {
+    case "branches-dependantes":
+      return `${body.message} \u2014 ${String(detail.branches.length)} branche(s) en dependent : ${detail.branches.join(", ")}. Promouvez-les ou supprimez-les avant d effacer la base parente.`;
+    case "base-endormie":
+      return `${body.message} \u2014 la base ${detail.ref} dort. Reveillez-la et reessayez.`;
+    case "place-insuffisante": {
+      const manque = detail.requiredBytes - detail.availableBytes;
+      return `${body.message} \u2014 il manque ${String(manque)} octets sur cette machine. Liberez de la place ou placez la base ailleurs.`;
+    }
+  }
+}
+
+// src/operations.ts
+import { z as z2 } from "zod";
+var resourceRef = z2.string().min(1).max(200);
+var resourceName = z2.string().min(1).max(200);
+var idempotencyKey = z2.string().min(8).max(200);
+var provisioned = z2.object({
+  ref: resourceRef,
+  /**
+   * La chaine de connexion, rendue **une seule fois**.
+   *
+   * L'agent ne sait pas la relire : il ne conserve pas le mot de passe, il
+   * conserve ce que PostgreSQL en garde. Une reprise passe par une rotation,
+   * jamais par une relecture — c'est ce qui fait qu'un agent compromis ne
+   * livre pas le parc.
+   */
+  connectionString: z2.string().min(1),
+  /** La region telle que l'agent la connait. Voir la note du module. */
+  region: z2.string().min(1)
+});
+var hostedResource = z2.object({
+  ref: resourceRef,
+  name: resourceName,
+  /** L'agent la considere-t-il utilisable ? */
+  available: z2.boolean(),
+  region: z2.string().min(1),
+  /**
+   * Endormie ou non.
+   *
+   * Distinct de `available` : une base endormie est parfaitement saine. Les
+   * confondre ferait passer une economie voulue pour une panne, et la
+   * reconciliation ouvrirait un incident a chaque client au repos.
+   */
+  sleeping: z2.boolean(),
+  /**
+   * La ressource dont celle-ci est un clone, s'il y en a une.
+   *
+   * C'est ce qui permet de savoir, avant de demander une suppression, qu'elle
+   * sera refusee.
+   */
+  parentRef: resourceRef.optional()
+});
+var measuredUsage = z2.object({
+  ref: resourceRef,
+  /** Octets reellement occupes par le dataset, instantanes compris. */
+  storageBytes: z2.number().int().nonnegative(),
+  /** Secondes pendant lesquelles le calcul a tourne sur la periode. */
+  computeSeconds: z2.number().nonnegative(),
+  /** Debut de la periode couverte. */
+  from: z2.iso.datetime(),
+  /** Fin de la periode couverte. */
+  to: z2.iso.datetime(),
+  /**
+   * Quand la mesure a ete prise.
+   *
+   * Distinct de `to` : une mesure peut couvrir une periode close il y a une
+   * heure. C'est cet horodatage-ci que la regle de peremption regarde.
+   */
+  measuredAt: z2.iso.datetime()
+});
+var agentHealth = z2.object({
+  nodeId: z2.string().min(1),
+  /** Sert-il, oui ou non. Un agent qui doute repond `false`. */
+  serving: z2.boolean(),
+  /** Bases hebergees, endormies comprises. */
+  hosted: z2.number().int().nonnegative(),
+  /** Place restante sur le pool. Ce qui decide d'un placement. */
+  availableBytes: z2.number().int().nonnegative(),
+  /**
+   * Depuis quand l'agent tourne.
+   *
+   * Un agent qui vient de redemarrer et qui sert deja est le signe d'un
+   * redemarrage non demande : quelque chose l'a tue.
+   */
+  startedAt: z2.iso.datetime(),
+  /** Version, pour qu'un parc heterogene se voie. */
+  version: z2.string().min(1)
+});
+var createDatabaseRequest = z2.object({
+  name: resourceName,
+  region: z2.string().min(1),
+  idempotencyKey
+});
+var createBranchRequest = z2.object({
+  name: resourceName,
+  parentRef: resourceRef,
+  idempotencyKey
+});
+var OPERATIONS = [
+  {
+    id: "createDatabase",
+    method: "POST",
+    path: "/v1/databases",
+    request: createDatabaseRequest,
+    response: provisioned,
+    mutating: true
+  },
+  {
+    id: "createBranch",
+    method: "POST",
+    path: "/v1/databases/:ref/branches",
+    request: createBranchRequest,
+    response: provisioned,
+    mutating: true
+  },
+  {
+    id: "deleteDatabase",
+    method: "DELETE",
+    path: "/v1/databases/:ref",
+    request: void 0,
+    response: z2.object({ deleted: z2.literal(true) }),
+    mutating: true
+  },
+  {
+    id: "suspend",
+    method: "POST",
+    path: "/v1/databases/:ref/suspend",
+    request: void 0,
+    response: z2.object({ sleeping: z2.literal(true) }),
+    mutating: true
+  },
+  {
+    id: "resume",
+    method: "POST",
+    path: "/v1/databases/:ref/resume",
+    request: void 0,
+    response: z2.object({ sleeping: z2.literal(false) }),
+    mutating: true
+  },
+  {
+    id: "list",
+    method: "GET",
+    path: "/v1/databases",
+    request: void 0,
+    response: z2.object({ resources: z2.array(hostedResource) }),
+    mutating: false
+  },
+  {
+    id: "rotateCredentials",
+    method: "POST",
+    path: "/v1/databases/:ref/credentials",
+    request: void 0,
+    response: z2.object({ connectionString: z2.string().min(1) }),
+    mutating: true
+  },
+  {
+    id: "usage",
+    method: "GET",
+    path: "/v1/databases/:ref/usage",
+    request: void 0,
+    response: measuredUsage,
+    mutating: false
+  },
+  {
+    id: "health",
+    method: "GET",
+    path: "/v1/health",
+    request: void 0,
+    response: agentHealth,
+    mutating: false
+  }
+];
+var errorResponse = failureBody;
+function operation(id) {
+  const found = OPERATIONS.find((op) => op.id === id);
+  if (found === void 0) throw new Error(`Operation inconnue : ${id}`);
+  return found;
+}
+function pathFor(op, ref) {
+  if (!op.path.includes(":ref")) return op.path;
+  if (ref === void 0) {
+    throw new Error(`L operation ${op.id} attend une reference.`);
+  }
+  return op.path.replace(":ref", encodeURIComponent(ref));
+}
+var IDEMPOTENT_OPERATIONS = OPERATIONS.filter(
+  (op) => op.request !== void 0 && "idempotencyKey" in op.request.shape
+).map((op) => op.id);
+export {
+  IDEMPOTENT_OPERATIONS,
+  OPERATIONS,
+  STATUS_BY_KIND,
+  agentHealth,
+  createBranchRequest,
+  createDatabaseRequest,
+  describeFailure,
+  errorResponse,
+  failureBody,
+  failureDetail,
+  failureKind,
+  hostedResource,
+  idempotencyKey,
+  isRetryable,
+  measuredUsage,
+  operation,
+  pathFor,
+  provisioned,
+  resourceName,
+  resourceRef
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@odoro-cli/fleet-protocol",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Le contrat entre le plan de controle Odoro et un agent de flotte.",
+  "license": "UNLICENSED",
+  "author": "Odoro",
+  "homepage": "https://github.com/ODORO-CLI/odoro-fleet#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ODORO-CLI/odoro-fleet.git",
+    "directory": "packages/protocol"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "zod": "^4.5.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "zod": "^4.5.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}