<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Randy Aries Saputra</title>
    <description>The latest articles on DEV Community by Randy Aries Saputra (@ariesrandy).</description>
    <link>https://dev.to/ariesrandy</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F3982044%2F2e2fe0b9-bf89-4a89-9fdd-ea889c180cc9.jpg</url>
      <title>DEV Community: Randy Aries Saputra</title>
      <link>https://dev.to/ariesrandy</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/ariesrandy"/>
    <language>en</language>
    <item>
      <title>How BabySea built a regional event spine on Confluent and AWS</title>
      <dc:creator>Randy Aries Saputra</dc:creator>
      <pubDate>Sun, 22 Nov 2026 03:13:13 +0000</pubDate>
      <link>https://dev.to/ariesrandy/how-babysea-built-a-regional-event-spine-on-confluent-and-aws-1p4c</link>
      <guid>https://dev.to/ariesrandy/how-babysea-built-a-regional-event-spine-on-confluent-and-aws-1p4c</guid>
      <description>&lt;p&gt;&lt;strong&gt;TL;DR.&lt;/strong&gt; BabySea moves execution facts through a regional Confluent + AWS event spine, but Postgres stays the source of truth and the API never waits on the stream. The result is an event-driven system that is not event-dependent.&lt;/p&gt;

&lt;p&gt;This post is not a Kafka comparison, or a generic streaming tutorial. It is the architecture and boundary discipline behind one specific production decision: how an AI execution control plane can stream operational facts without making customer requests more fragile.&lt;/p&gt;




&lt;p&gt;Event infrastructure is useful only if it makes the product more capable without making the request path more fragile.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://babysea.ai" rel="noopener noreferrer"&gt;BabySea&lt;/a&gt; is the execution control plane for generative media: one API across image and video models, inference providers, sovereign regions, credit settlement, webhook delivery, provider failover, and adaptive routing. Every generation creates operational facts. A request is accepted. A provider is tried. A timeout happens. Credits are reserved or refunded. A webhook is delivered. A ranking system learns from the outcome.&lt;/p&gt;

&lt;p&gt;Those facts need to move.&lt;/p&gt;

&lt;p&gt;But they should not decide whether a customer request can run.&lt;/p&gt;

&lt;p&gt;That is why we built BabySea's regional event spine on &lt;a href="https://www.confluent.io" rel="noopener noreferrer"&gt;Confluent&lt;/a&gt; and &lt;a href="https://aws.amazon.com" rel="noopener noreferrer"&gt;AWS&lt;/a&gt;, with regional Postgres as the operational source of truth, Confluent Cloud Kafka and Schema Registry as the event contract layer, &lt;a href="https://www.databricks.com" rel="noopener noreferrer"&gt;Databricks&lt;/a&gt; Spark Structured Streaming and Delta Lake as the governed consumer path, and &lt;a href="https://upstash.com" rel="noopener noreferrer"&gt;Upstash&lt;/a&gt; as the hot-path cache for provider-ranking artifacts.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Confluent moves schema-valid execution facts.
It does not own product correctness.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That boundary is the whole architecture.&lt;/p&gt;

&lt;h2&gt;
  
  
  The source of truth stays in Postgres
&lt;/h2&gt;

&lt;p&gt;The easiest way to make an event-driven system brittle is to let the stream become the source of truth for operational state.&lt;/p&gt;

&lt;p&gt;BabySea does not do that.&lt;/p&gt;

&lt;p&gt;When a customer starts a generation, the authoritative state lives in regional Postgres. That is where generation lifecycle, provider attempts, credit invariants, account boundaries, tenant ownership, and webhook intent are protected. Confluent receives facts after the operational transaction has produced durable intent.&lt;/p&gt;

&lt;p&gt;The system contract is deliberately simple:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Postgres owns correctness.
Confluent Cloud Kafka transports facts.
Confluent Schema Registry enforces event contracts.
AWS runs the publisher outside the request path.
Databricks Spark Structured Streaming lands validated events in Delta Lake.
Upstash serves compact ranking artifacts.
The API keeps serving when downstream systems degrade.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That last line matters most. Confluent Kafka is allowed to lag. Confluent Schema Registry is allowed to be unavailable. The Databricks Structured Streaming job is allowed to pause. A cache export is allowed to be stale. None of those conditions should stop the API from accepting a valid generation request or settling its lifecycle correctly.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;The event spine is allowed to be behind. It is not allowed to become the reason customer execution fails.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  The outbox is the boundary between local correctness and distributed facts
&lt;/h2&gt;

&lt;p&gt;BabySea does not publish directly to Kafka from the request handler.&lt;/p&gt;

&lt;p&gt;Instead, the application writes event intent into a transactional outbox in the same regional database that commits the operational state. A separate publisher claims those rows, validates them, publishes to Confluent, and marks them published only after Kafka acknowledgement.&lt;/p&gt;

&lt;p&gt;Conceptually, the path looks like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Customer request
  -&amp;gt; API validates and commits business state
  -&amp;gt; database records event intent in the outbox
  -&amp;gt; AWS ECS publisher claims pending rows
  -&amp;gt; publisher validates envelope, topic, key, type, and schema
  -&amp;gt; publisher sends to Confluent
  -&amp;gt; row is marked published after acknowledgement
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The transaction shape is the important part. The outbox write happens with the product write, not after it as a best-effort side effect:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;begin&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;-- The product row is the source of truth.&lt;/span&gt;
&lt;span class="k"&gt;insert&lt;/span&gt; &lt;span class="k"&gt;into&lt;/span&gt; &lt;span class="n"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;file_assets&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;account_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;model_identifier&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;generation_status&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;generation_region&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;values&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;generation_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;account_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;model_identifier&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s1"&gt;'processing'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;region&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;-- The event is durable intent to publish, not the authority.&lt;/span&gt;
&lt;span class="k"&gt;select&lt;/span&gt; &lt;span class="n"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;enqueue_event_outbox&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;p_region&lt;/span&gt; &lt;span class="o"&gt;:=&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;region&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;p_topic&lt;/span&gt; &lt;span class="o"&gt;:=&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;generation_topic&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;p_event_type&lt;/span&gt; &lt;span class="o"&gt;:=&lt;/span&gt; &lt;span class="s1"&gt;'generation.requested.v1'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;p_partition_key&lt;/span&gt; &lt;span class="o"&gt;:=&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;generation_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;p_payload&lt;/span&gt; &lt;span class="o"&gt;:=&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;safe_event_payload&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;commit&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The publisher then owns distribution. Its job is intentionally narrow:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;batch&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="nf"&gt;claimOutboxBatches&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;region&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;row&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="n"&gt;batch&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nf"&gt;assertRegion&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;row&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;region&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="nf"&gt;assertAllowedTopic&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;topic&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="nf"&gt;assertSafePartitionKey&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;partition_key&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="nf"&gt;assertAllowedEventType&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;event_type&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="nf"&gt;assertNoSensitiveFields&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;payload&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;encoded&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;schemaRegistry&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;encode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;topic&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;payload&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

      &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;producer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;send&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;topic&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;topic&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;messages&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
          &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="n"&gt;key&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;partition_key&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
            &lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;encoded&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
          &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

      &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;markEventOutboxPublished&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;markEventOutboxFailed&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nf"&gt;classifyPublishError&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If the publisher is down, rows remain pending. If Confluent is unavailable, rows retry later. If Schema Registry cannot be reached, the publisher fails the row safely and backs off. The request path has already committed the product state and does not wait on the telemetry plane.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;The API produces durable intent.
The publisher performs distribution.
Those are different jobs.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Regions are part of the product contract
&lt;/h2&gt;

&lt;p&gt;BabySea operates across US, EU, and JP regional surfaces. The event system follows that boundary instead of collapsing everything into one global stream.&lt;/p&gt;

&lt;p&gt;Each region has its own Confluent topic surface, Schema Registry subjects, publisher deployment, Databricks Structured Streaming job, Delta bronze table, and routing artifacts. That separation is not cosmetic. Provider behavior is regional. Latency is regional. Cost and reliability profiles are regional. Customer data boundaries are regional. A generation event produced in one region should not quietly become an input to another region's operational loop.&lt;/p&gt;

&lt;p&gt;The regional pattern is straightforward:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;US region -&amp;gt; US event spine -&amp;gt; US lakehouse catalog -&amp;gt; US ranking cache
EU region -&amp;gt; EU event spine -&amp;gt; EU lakehouse catalog -&amp;gt; EU ranking cache
JP region -&amp;gt; JP event spine -&amp;gt; JP lakehouse catalog -&amp;gt; JP ranking cache
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Regional architecture is not a deployment detail for BabySea. It is part ofthe execution contract.&lt;/p&gt;

&lt;p&gt;This is why our topics, schemas, ingestion jobs, and cache artifacts are region-scoped. The exact resource identifiers are an implementation detail; the invariant is the important part.&lt;/p&gt;

&lt;h2&gt;
  
  
  Schema Registry keeps the stream from becoming JSON entropy
&lt;/h2&gt;

&lt;p&gt;An event stream without schema discipline eventually becomes distributed JSON entropy.&lt;/p&gt;

&lt;p&gt;BabySea uses Confluent Schema Registry so event payloads evolve as contracts, not as ad hoc logs. The event families cover the parts of execution that downstream systems need to observe:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;generation lifecycle&lt;/li&gt;
&lt;li&gt;provider attempt outcomes&lt;/li&gt;
&lt;li&gt;credit reservation and settlement events&lt;/li&gt;
&lt;li&gt;webhook delivery outcomes&lt;/li&gt;
&lt;li&gt;provider health updates&lt;/li&gt;
&lt;li&gt;dead-letter records for contract failures&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The envelope matters as much as the payload. Every event needs stable identity, region, type, source, timestamp, and partitioning semantics. The payload then carries product facts needed by analytics, routing intelligence, operational inspection, or downstream consumers.&lt;/p&gt;

&lt;p&gt;A generation event payload is shaped like an operational contract, not a log dump:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"evt_01hx_sanitized"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"generation.completed.v1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"source"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"babysea.api"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"region"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"us"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"occurred_at"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"2026-05-10T21:42:00.000Z"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"partition_key"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"gen_01hx_sanitized"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"data"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"generation_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"gen_01hx_sanitized"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"account_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"acct_sanitized"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"model_identifier"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"openai/gpt-image-1-mini"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"media_type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"image"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"succeeded"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"provider_used"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"openai"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"credit_outcome"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"charged"&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That example is intentionally boring. It is useful downstream because it is stable, typed, regional, and safe to process. It does not contain the customer prompt, generated files, signed URLs, API keys, webhook secrets, or provider credentials.&lt;/p&gt;

&lt;p&gt;The security boundary is equally important. The event spine should not become a second uncontrolled customer-data lake.&lt;/p&gt;

&lt;p&gt;BabySea's event payload rules are intentionally strict:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;No prompts.
No raw files.
No output URLs.
No webhook secrets.
No API key values.
No unnecessary customer PII.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Those rules are enforced through schema design, publisher validation, review discipline, and production-readiness checks.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Observability should not require leaking customer intent or private artifacts into the event stream&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  AWS runs the publisher outside the product API
&lt;/h2&gt;

&lt;p&gt;The event publisher runs on AWS ECS Fargate, separate from the customer-serving API.&lt;/p&gt;

&lt;p&gt;That separation gives us operational control. The publisher can be deployed, paused, scaled, rolled back, inspected, and hardened independently. It has one responsibility: drain the outbox safely.&lt;/p&gt;

&lt;p&gt;The publisher validates before publish:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;region&lt;/li&gt;
&lt;li&gt;topic family&lt;/li&gt;
&lt;li&gt;partition key&lt;/li&gt;
&lt;li&gt;event type&lt;/li&gt;
&lt;li&gt;envelope shape&lt;/li&gt;
&lt;li&gt;schema compatibility&lt;/li&gt;
&lt;li&gt;payload safety&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;It only marks a row as published after Confluent acknowledges the write. Everything else remains retryable or dead-lettered according to the failure mode.&lt;/p&gt;

&lt;p&gt;The AWS surface around that worker is conventional but important: container runtime, secrets, IAM boundaries, networking, logs, and encrypted staging/checkpoint storage for downstream processing. Those details matter operationally, but the public architecture does not depend on exposing exact names, IDs, or endpoints.&lt;/p&gt;

&lt;p&gt;The important behavior is this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;API request succeeds.
Outbox row persists.
Publisher publishes when dependencies are healthy.
Downstream systems catch up.
Customer traffic continues.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That gives BabySea decoupling without hand-waving over reliability.&lt;/p&gt;

&lt;h2&gt;
  
  
  Confluent feeds Spark Structured Streaming, not the request path
&lt;/h2&gt;

&lt;p&gt;Confluent's primary downstream consumer today is a Databricks Spark Structured Streaming job using the native Kafka source.&lt;/p&gt;

&lt;p&gt;Regional Structured Streaming jobs read generation events from Confluent Cloud Kafka, decode Confluent JSON Schema Registry payloads, validate envelope fields, reject malformed or wrong-region records, deduplicate by event identity, and land validated rows into Delta Lake bronze tables.&lt;/p&gt;

&lt;p&gt;The notebook logic is deliberately defensive. It treats the stream as an input that must prove it belongs in the regional lakehouse:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;pyspark&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;sql&lt;/span&gt; &lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;functions&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="no"&gt;F&lt;/span&gt;

&lt;span class="n"&gt;raw&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;spark&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;readStream&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nb"&gt;format&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"kafka"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;option&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"kafka.bootstrap.servers"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;kafka_bootstrap&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;option&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"subscribe"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;generation_topic&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;option&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"startingOffsets"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"latest"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;load&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="n"&gt;decoded&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;decode_confluent_json_schema&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;schema_registry_subject&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="n"&gt;valid_generation_events&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;decoded&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;where&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;F&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;col&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"region"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="no"&gt;F&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;lit&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;REGION&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;where&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;F&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;col&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isin&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="s2"&gt;"generation.requested.v1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="s2"&gt;"generation.completed.v1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="s2"&gt;"generation.failed.v1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;where&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;F&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;col&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"id"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isNotNull&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;where&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;F&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;col&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"data.generation_id"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isNotNull&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;dropDuplicates&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"id"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;valid_generation_events&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;writeStream&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nb"&gt;format&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"delta"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;option&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"checkpointLocation"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;checkpoint_path&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;outputMode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"append"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toTable&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="s2"&gt;"{CATALOG}.streaming.bronze_generation_events"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Malformed events, wrong-region events, and non-generation records do not become bronze rows. That keeps the lakehouse ingestion path honest: streaming bronze is a validated event substrate, not a mirror of every byte that arrives on Confluent Kafka.&lt;/p&gt;

&lt;p&gt;That streaming bronze layer gives the lakehouse a governed event substrate. It can power operational analytics, quality checks, and learning loops without asking the operational database to serve every downstream workload directly.&lt;/p&gt;

&lt;p&gt;But the same rule still applies:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Databricks Spark Structured Streaming is on the learning path. It is not on the customer request path.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;BabySea's adaptive routing loop learns from execution outcomes. The Databricks lakehouse computes provider-performance and ranking artifacts by model and region after Confluent has delivered validated events. Upstash stores the compact serving artifact. The API reads that cached artifact when a customer asks for fastest routing.&lt;/p&gt;

&lt;p&gt;The hot path does not read Kafka. It does not call Databricks. It does not compute online features. It reads a cache value, validates it, filters it against configured providers, and falls back to deterministic provider order if anything is missing, stale, malformed, or unavailable.&lt;/p&gt;

&lt;p&gt;That code path is intentionally small:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;resolveProviderOrder&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;region&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;DeploymentRegion&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;providerOrder&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;configuredProviders&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;ProviderName&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;fallbackOrder&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;configuredProviders&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;', '&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;providerOrder&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="s1"&gt;'fastest'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;providerOrder&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;ranking&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;getCachedRanking&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;region&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;model&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;allowed&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Set&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;configuredProviders&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;rankedProviders&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;ranking&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;providersRanked&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt;
    &lt;span class="n"&gt;allowed&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;has&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;rankedProviders&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="n"&gt;rankedProviders&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;', '&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;fallbackOrder&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The cache parser is written with the same posture as the event ingestion path: validate structure, return &lt;code&gt;null&lt;/code&gt; on contract failure, and let the caller fall back. A malformed ranking is not an exception path for customer traffic. It is a signal that the intelligence layer should be inspected.&lt;/p&gt;

&lt;p&gt;That is the serving contract:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Confluent stream -&amp;gt; Databricks learning layer -&amp;gt; Upstash cache -&amp;gt; API routing
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Not:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;API request -&amp;gt; Confluent Kafka read -&amp;gt; Databricks query -&amp;gt; routing decision
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The event spine helps the system learn. It does not make every request wait for the learning system.&lt;/p&gt;

&lt;p&gt;That boundary is what makes adaptive infrastructure safe.&lt;/p&gt;

&lt;h2&gt;
  
  
  Dead letters are evidence, not shame
&lt;/h2&gt;

&lt;p&gt;Real event systems see malformed records, incompatible changes, regional mismatches, poison messages, transient network errors, and consumer bugs.&lt;/p&gt;

&lt;p&gt;Pretending otherwise is not engineering. It is optimism.&lt;/p&gt;

&lt;p&gt;BabySea treats dead-letter records as operational evidence. The DLQ is not the first line of defense; validation, schema compatibility, outbox retry state, and lag visibility come first. The DLQ exists for records that cannot safely move forward after those mechanisms have done their job.&lt;/p&gt;

&lt;p&gt;The desired behavior is boring:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Good events keep flowing.
Bad events are isolated.
Operators get evidence.
The API keeps serving.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That boring behavior is exactly what production systems need.&lt;/p&gt;

&lt;h2&gt;
  
  
  Readiness is checked, not remembered
&lt;/h2&gt;

&lt;p&gt;Distributed systems drift.&lt;/p&gt;

&lt;p&gt;One region gets a schema update. Another misses a notebook import. A legacy connector path accidentally returns. A fail-open fallback gets weakened during a refactor. A payload starts carrying a field that should never leave the operational database.&lt;/p&gt;

&lt;p&gt;So BabySea treats production readiness as a checked property, not a shared memory.&lt;/p&gt;

&lt;p&gt;Our guardrails verify the things that would hurt the system if they drifted:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;regional implementation parity after normalization&lt;/li&gt;
&lt;li&gt;DB-backed event payload fields match schema contracts&lt;/li&gt;
&lt;li&gt;removed connector paths stay removed&lt;/li&gt;
&lt;li&gt;Databricks Structured Streaming ingestion remains aligned with the deployed Delta tables&lt;/li&gt;
&lt;li&gt;schedules are not accidentally paused by default&lt;/li&gt;
&lt;li&gt;payload safety rules stay intact&lt;/li&gt;
&lt;li&gt;fail-open behavior remains true for downstream failures&lt;/li&gt;
&lt;/ul&gt;

&lt;blockquote&gt;
&lt;p&gt;In distributed systems, consistency is not a vibe. It has to be checked.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;The goal is not to prove that Kafka exists. The goal is to prove that adding Kafka did not weaken the execution path.&lt;/p&gt;

&lt;h2&gt;
  
  
  What we validated end to end
&lt;/h2&gt;

&lt;p&gt;We validated the implementation across US, EU, and JP with image and video workloads, successful and failed generation states, outbox publication, Confluent topics and schemas, Databricks Spark Structured Streaming ingestion, provider-ranking export, and cache-backed fastest routing.&lt;/p&gt;

&lt;p&gt;The validation flow was intentionally ordered instead of synthetic. Each region ran the same media plan: image workloads, video workloads, fastest routing, successful executions, and insufficient-credit failures where the account state made that path valid. No failed request was retried, because retrying would have hidden the failure invariant we wanted to observe.&lt;/p&gt;

&lt;p&gt;The high-level result:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Check&lt;/th&gt;
&lt;th&gt;Result&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Regions&lt;/td&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Ordered generation requests&lt;/td&gt;
&lt;td&gt;21&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Successful generations&lt;/td&gt;
&lt;td&gt;17&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Clean insufficient-credit failures&lt;/td&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Generation outbox rows&lt;/td&gt;
&lt;td&gt;14 per region&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Confluent topic families present&lt;/td&gt;
&lt;td&gt;6 per region&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Schema subjects present&lt;/td&gt;
&lt;td&gt;5 per region&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Streaming bronze generation rows&lt;/td&gt;
&lt;td&gt;14 per region&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Failed request retries&lt;/td&gt;
&lt;td&gt;0&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The most useful validation cases were not only the happy paths.&lt;/p&gt;

&lt;p&gt;One set of requests failed cleanly because the account did not have enough credits. Those requests still produced source-of-truth failure state and failure telemetry, but they did not reach provider execution, did not reserve credits, and did not charge credits.&lt;/p&gt;

&lt;p&gt;Another provider path timed out in a separate fail-open check and the system failed over to the next eligible provider.&lt;/p&gt;

&lt;p&gt;Those are the tests that matter. Not just whether events move, but whether the product remains correct when execution takes the messy path.&lt;/p&gt;

&lt;p&gt;The validation logic we care about looks more like invariants than screenshots:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;summary&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;requestsTotal&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;21&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;summary&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;succeededTotal&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;17&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;summary&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;failedTotal&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;4&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;summary&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;failedRequestRetryCount&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;region&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'us'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'eu'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'jp'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;regionState&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;region&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;confluent&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;topicsOk&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;6&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;regionState&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;region&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;confluent&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;subjectsOk&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;5&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;regionState&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;region&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;outbox&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;publishedGenerationRows&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;14&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;regionState&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;region&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;databricks&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;bronzeRows&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;14&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;failed&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="n"&gt;insufficientCreditFailures&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;failed&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;providerExecutionStarted&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;failed&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;creditReserved&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;failed&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;creditCharged&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;failed&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;failureEventPublished&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Insufficient credits -&amp;gt; failure telemetry, no provider execution, no charge
Publisher unavailable -&amp;gt; outbox waits, API continues
Confluent unavailable -&amp;gt; publisher retries, API continues
Structured Streaming paused -&amp;gt; Confluent retains events and the stream catches up later, API continues
Upstash unavailable -&amp;gt; static provider order, API continues
Provider timeout -&amp;gt; failover, API continues when another provider succeeds
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The architecture is only useful if it works when something else is having a bad day.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why Confluent is the right layer
&lt;/h2&gt;

&lt;p&gt;Confluent gives BabySea a managed regional Kafka and Schema Registry surface for durable event movement. That matters because the platform has multiple event families, multiple regional boundaries, and multiple downstream consumers. The operational database should not be responsible for serving every analytics, streaming, validation, and learning workload directly.&lt;/p&gt;

&lt;p&gt;Confluent is the right middle layer because it gives us:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;durable regional event transport&lt;/li&gt;
&lt;li&gt;governed schema evolution&lt;/li&gt;
&lt;li&gt;replayable event history within retention&lt;/li&gt;
&lt;li&gt;producer and consumer isolation&lt;/li&gt;
&lt;li&gt;a stable ingestion path into Databricks&lt;/li&gt;
&lt;li&gt;operational visibility around the event spine&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;But Confluent is valuable only because the boundary is clear.&lt;/p&gt;

&lt;p&gt;If the API synchronously depended on Kafka publish, the system would be fragile. If Confluent became the credit or generation source of truth, the system would be confused. If Databricks became a request-path dependency, the learning loop would become a reliability risk. If Upstash cache misses broke routing, the cache would be overfit.&lt;/p&gt;

&lt;p&gt;The value is not that BabySea added Kafka.&lt;/p&gt;

&lt;p&gt;The value is that BabySea added a regional event spine without weakening the core execution path.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;The best infrastructure layers make the system more capable&lt;br&gt;
without making the product more fragile&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  The broader point
&lt;/h2&gt;

&lt;p&gt;AI infrastructure is becoming a distributed systems problem faster than most teams expected.&lt;/p&gt;

&lt;p&gt;Calling models is the easy part. The hard part is controlling execution across providers, regions, failures, credits, webhooks, customer workloads, and learning loops. Every request produces operational knowledge. Every provider attempt is a signal. Every timeout teaches the system something.&lt;/p&gt;

&lt;p&gt;But learning from execution requires moving facts safely.&lt;/p&gt;

&lt;p&gt;That is what the Confluent spine gives BabySea: a governed, regional, schema-valid way to move execution facts out of the operational core and into the systems that can learn from them.&lt;/p&gt;

&lt;p&gt;The product database remains authoritative. Confluent distributes facts. Databricks Spark Structured Streaming lands those facts into Delta Lake. The lakehouse turns them into intelligence. Upstash serves the learned artifact. The API owns request correctness.&lt;/p&gt;

&lt;p&gt;That separation is the architecture.&lt;/p&gt;

&lt;p&gt;And it is why BabySea can keep improving provider selection, operational analytics, and execution quality without letting the intelligence plane become a liability for customer traffic.&lt;/p&gt;

&lt;p&gt;The future of AI infrastructure belongs to systems that can learn continuously and fail safely.&lt;/p&gt;

&lt;p&gt;That is what we are building.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>kafka</category>
      <category>confluent</category>
      <category>aws</category>
    </item>
    <item>
      <title>How BabySea built adaptive provider selection on Databricks</title>
      <dc:creator>Randy Aries Saputra</dc:creator>
      <pubDate>Sun, 22 Nov 2026 03:09:26 +0000</pubDate>
      <link>https://dev.to/ariesrandy/how-babysea-built-adaptive-provider-selection-on-databricks-4g39</link>
      <guid>https://dev.to/ariesrandy/how-babysea-built-adaptive-provider-selection-on-databricks-4g39</guid>
      <description>&lt;p&gt;&lt;a href="https://babysea.ai" rel="noopener noreferrer"&gt;BabySea&lt;/a&gt; is the execution control plane for generative media: one API across 80+ image and video models from 12+ AI labs, served by 8+ inference providers, running in three sovereign regions: US, EU, and APAC. The hard problem is not exposing models. The hard problem is execution: deciding, per request, which provider should actually run a given model in a given region under real latency, reliability, and cost conditions. Static routing breaks down quickly in that environment, and &lt;a href="https://www.databricks.com" rel="noopener noreferrer"&gt;Databricks&lt;/a&gt; is the intelligence layer that makes our provider selection adaptive instead of static.&lt;/p&gt;

&lt;p&gt;At BabySea, every customer execution produces an attempt record (provider, model, submitted/resolved timestamps, outcome, estimated cost, failover order, and cancellation state) and that attempt stream lands first in our regional &lt;a href="https://supabase.com" rel="noopener noreferrer"&gt;Supabase&lt;/a&gt; systems, because Postgres is the operational source of truth for the product. The deployment region is kept as a regional stack boundary and written into Databricks Bronze/Gold outputs. From there, Databricks runs the learning loop end to end in production. The architectural decision that matters most is this: we did not build a detached analytics estate beside the product, we made Databricks part of the control loop that improves execution outcomes while keeping the customer-serving path operationally safe.&lt;/p&gt;

&lt;h2&gt;
  
  
  Databricks is on the learning path, not the request path
&lt;/h2&gt;

&lt;p&gt;That boundary is the whole design. A common failure mode in "smart routing" systems is to let the intelligence plane become a hard dependency for serving traffic, so the first time the ranking service degrades, the customer-visible path degrades with it. We built the opposite system: Databricks computes the ranking, the API consumes a cached export of that ranking in milliseconds, and the API always retains deterministic fallback behavior if Databricks or cache infrastructure degrade.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Adaptive selection is an enhancement, never a dependency&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;The runtime chain is straightforward: customer traffic produces provider-attempt telemetry in regional Supabase, Databricks reads that telemetry directly and transforms it into provider-performance and provider-ranking artifacts, those rankings are exported into &lt;a href="https://upstash.com" rel="noopener noreferrer"&gt;Upstash&lt;/a&gt;, the API reads the exported ranking for &lt;code&gt;generation_provider_order: "fastest"&lt;/code&gt; while circuit-breaker logic and failover stay in place, and later customer traffic generates new telemetry that closes the loop. That loop is the core of the design, and every workload makes later workloads smarter.&lt;/p&gt;

&lt;p&gt;Here is what the API actually does when a customer asks for &lt;code&gt;"fastest"&lt;/code&gt;. This is the hot path, not pseudocode:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;deploymentRegion&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;getDeploymentRegion&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;providerOrder&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s1"&gt;'fastest'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;ranking&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;getCachedRanking&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;model&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;deploymentRegion&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;configuredProviders&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Set&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;Object&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;keys&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;providerLookup&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;fromCache&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;ranking&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;providersRanked&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt;
    &lt;span class="n"&gt;configuredProviders&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;has&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;fromCache&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;fromCache&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;resolvedOrder&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;fromCache&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;', '&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;providerOrderSource&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'cached-ranking'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;resolvedOrder&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;converters&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;providerDisplayOrder&lt;/span&gt;
      &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;configuredProviders&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;has&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
      &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;', '&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;providerOrderSource&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'fallback'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Notice what is not in that code. There is no Databricks SDK call, no MLflow client, and no Mosaic AI Model Serving fetch. The hot path reads one Upstash Redis-protocol key, filters it against the providers configured for the requested model, and moves on. Everything Databricks does happens upstream of this line.&lt;/p&gt;

&lt;h2&gt;
  
  
  Zero-ETL ingress with Unity Catalog and Lakehouse Federation
&lt;/h2&gt;

&lt;p&gt;The first Databricks decision was to avoid copying operational data unless we had a compelling reason to. We use Unity Catalog Lakehouse Federation to connect each regional Databricks workspace to its matching regional Supabase database through a PostgreSQL foreign connection. That gives us a governed entry point into operational routing telemetry without introducing another ETL system, another CDC estate, or another set of consistency problems between the product database and the learning system. This is not just a convenience feature, it changes the operating model.&lt;/p&gt;

&lt;p&gt;Because the federated source sits under Unity Catalog, governance starts at ingress. Federated source columns carry governed tags such as &lt;code&gt;gdpr_status&lt;/code&gt;, &lt;code&gt;tenant_boundary&lt;/code&gt;, and &lt;code&gt;ai_telemetry&lt;/code&gt;, and those tags matter because the routing system is not just reading "logs", it is reading multi-tenant, region-sensitive execution data that will feed training, ranking, analytics, and operational validation. That means the same control plane that reads provider telemetry also knows which fields are tenant-isolating keys, which fields are compliance-sensitive, and which fields are cost or inference telemetry, with lineage originating at the operational source rather than at a copied derivative. For a multi-region AI infrastructure company, that is a cleaner foundation than shipping raw operational tables into an ungoverned analytics sink and reconstructing meaning later.&lt;/p&gt;

&lt;h2&gt;
  
  
  Medallion design for routing intelligence, not generic analytics
&lt;/h2&gt;

&lt;p&gt;From the federated source, we refine the data through a Lakeflow Spark Declarative Pipeline into a Bronze, Silver, Gold medallion on Delta Lake. This is not medallion architecture as ceremony: each layer has a specific role in the routing loop.&lt;/p&gt;

&lt;h3&gt;
  
  
  Bronze
&lt;/h3&gt;

&lt;p&gt;Bronze lands the federated operational tables into Delta-backed materialized views. Its job is not business logic, its job is isolation and reproducibility: isolate the product database from downstream transformations, preserve lineage, and establish a Delta-native substrate for analytics, training, and export. In our production stack, the most important Bronze inputs are the attempt-log path that eventually becomes routing intelligence.&lt;/p&gt;

&lt;h3&gt;
  
  
  Silver
&lt;/h3&gt;

&lt;p&gt;Silver is where the routing contract becomes explicit. Provider attempts are cleaned, typed, normalized, and enriched with routing-relevant fields such as latency, success, wasted-attempt semantics, time buckets, and other derived fields needed for aggregation and training. Silver is where "application logs" stop being logs and become a feature-bearing execution dataset, and if you want reliable model training, reliable provider-performance analytics, or reliable ranking generation, this is the layer that has to be correct.&lt;/p&gt;

&lt;h3&gt;
  
  
  Gold
&lt;/h3&gt;

&lt;p&gt;Gold produces artifacts the rest of the platform can consume. That includes provider-performance aggregates, but the most important output is &lt;code&gt;gold_provider_ranking_by_model&lt;/code&gt;, which is the bridge between Databricks and the API.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;That Gold table is not a BI table.
It is a runtime contract.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  gold_provider_ranking_by_model: the bridge between data and execution
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;gold_provider_ranking_by_model&lt;/code&gt; emits one row per model and region, with ranked provider lists, scores, attempt totals, ranking-window metadata, and a computation timestamp. In the current production implementation, the ranking shape combines success rate, wasted-attempt rate, and latency normalization into a single score over a 24-hour window, which gives us a deterministic, explainable, continuously refreshed routing artifact even before any optional real-time model scoring enters the picture.&lt;/p&gt;

&lt;p&gt;Conceptually, the production scoring shape is:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;score = success_rate      * 1.0
      - wasted_rate       * COST_PENALTY
      - latency_p95_norm  * LATENCY_PENALTY
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;with current constants:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;COST_PENALTY = 0.5
LATENCY_PENALTY = 0.3
RANKING_WINDOW_HOURS = 24
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The reason this design works is simple. First, it gives the serving layer a compact, explicit object to consume: the API does not need raw execution logs, ad hoc joins, or online feature synthesis, it needs a ranking. Second, it lets the ML path and the non-ML path converge on the same abstraction, so whether the ranking is produced from direct aggregates, a registered predictive model, or both, the serving contract remains stable: here is the ordered provider set for this model in this region. That is what makes the system evolvable without destabilizing the API surface.&lt;/p&gt;

&lt;h2&gt;
  
  
  MLflow, Models in Unity Catalog, and regional model lifecycles
&lt;/h2&gt;

&lt;p&gt;On top of the medallion, we train a predictive routing model nightly with MLflow and register the resulting artifact in Models in Unity Catalog on a per-region basis (&lt;code&gt;babysea_us.ml.predictive_routing&lt;/code&gt;, &lt;code&gt;babysea_eu.ml.predictive_routing&lt;/code&gt;, &lt;code&gt;babysea_apac.ml.predictive_routing&lt;/code&gt;). In the implementation snapshot we documented, the latest READY model versions were US v8, EU v3, and APAC v3.&lt;/p&gt;

&lt;p&gt;That regional separation is not cosmetic. We operate across sovereign regions, and provider behavior, customer demand shape, cost conditions, and product constraints do not collapse neatly into a single global policy, so treating US, EU, and APAC as distinct learning domains is cleaner technically and safer operationally.&lt;/p&gt;

&lt;p&gt;The current production training notebook uses a value-prediction approach with a scikit-learn &lt;code&gt;GradientBoostingRegressor&lt;/code&gt;, not XGBoost. The serving features are intentionally compact (&lt;code&gt;provider&lt;/code&gt;, &lt;code&gt;model&lt;/code&gt;, &lt;code&gt;hour_of_day&lt;/code&gt;, &lt;code&gt;day_of_week&lt;/code&gt;) and the output is one scalar predicted value per provider candidate where higher means better. That score is not exposed directly to customers, it is one input into execution ordering, and the customer-facing abstraction remains stable even while the predictive layer evolves.&lt;/p&gt;

&lt;h2&gt;
  
  
  Adaptive routing as a production toggle
&lt;/h2&gt;

&lt;p&gt;Production Vercel deployments do not call Databricks on the request path. Databricks remains the internal learning system that exports Gold rankings to Upstash, and the API controls whether the &lt;code&gt;"fastest"&lt;/code&gt; sentinel should consume that cached adaptive ranking or fall back to the model's static provider order.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="no"&gt;ADAPTIVE_ROUTING_ENABLED&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;ADAPTIVE_ROUTING_ENABLED&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="s1"&gt;'false'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;providerOrder&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s1"&gt;'fastest'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;fallbackOrder&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;converters&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;providerDisplayOrder&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;configuredProviders&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;has&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;', '&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;ADAPTIVE_ROUTING_ENABLED&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;ranking&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;getCachedRanking&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;model&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;deploymentRegion&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;fromCache&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;ranking&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;providersRanked&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt;
      &lt;span class="n"&gt;configuredProviders&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;has&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;fromCache&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;resolvedOrder&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;fromCache&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;', '&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;resolvedOrder&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;fallbackOrder&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;resolvedOrder&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;fallbackOrder&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With &lt;code&gt;ADAPTIVE_ROUTING_ENABLED=true&lt;/code&gt; or unset, &lt;code&gt;"fastest"&lt;/code&gt; uses the Upstash ranking cache. With &lt;code&gt;ADAPTIVE_ROUTING_ENABLED=false&lt;/code&gt;, &lt;code&gt;"fastest"&lt;/code&gt; resolves to the static fallback order. In both modes, circuit-breaker sorting and provider failover still run.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;The difference between ML-enhanced infrastructure and ML-fragile infrastructure is whether the learning system is a hard dependency for every request. We do not let it become one.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;This is the architectural discipline that keeps the system safe.&lt;/p&gt;

&lt;h2&gt;
  
  
  Lakeflow Jobs as unattended orchestration
&lt;/h2&gt;

&lt;p&gt;The control loop is operationalized through Lakeflow Jobs. In production, the daily schedule is &lt;code&gt;02:30 UTC&lt;/code&gt; to export the Gold ranking into Upstash and &lt;code&gt;03:00 UTC&lt;/code&gt; to retrain and re-register the predictive model. Across three regions, that gives us six unattended jobs coordinating the routing loop: export and training in US, EU, and APAC.&lt;/p&gt;

&lt;p&gt;This schedule is not arbitrary. The export cadence, ranking window, and cache TTL are chosen as a system: a 24-hour Gold ranking window, a 48-hour Upstash TTL, and daily export cadence. That 48-hour TTL being deliberately longer than the 24-hour refresh cadence is what gives the system fail-open resilience, because yesterday's valid ranking can continue to serve even if today's job does not run. This is a subtle but important lesson in production ML systems: freshness is not the only variable that matters, graceful degradation matters just as much.&lt;/p&gt;

&lt;h2&gt;
  
  
  Upstash export and the hot-path contract
&lt;/h2&gt;

&lt;p&gt;The API never calls Databricks on the customer request path. Instead, a Lakeflow Job exports each Gold ranking row into Upstash using a key of the form &lt;code&gt;predictive:ranking:&amp;lt;region&amp;gt;:&amp;lt;model&amp;gt;&lt;/code&gt;, and the value includes &lt;code&gt;providers_ranked&lt;/code&gt;, &lt;code&gt;scores&lt;/code&gt;, &lt;code&gt;attempts_total&lt;/code&gt;, &lt;code&gt;window_hours&lt;/code&gt;, and &lt;code&gt;computed_at&lt;/code&gt;. Example shape:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"providers_ranked"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"cloudflare"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"replicate"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"fal"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"scores"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"cloudflare"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mf"&gt;0.81&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"replicate"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mf"&gt;0.42&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"fal"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mf"&gt;-0.05&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"attempts_total"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;137&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"window_hours"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;24&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"computed_at"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"2026-04-29T02:31:15Z"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That payload is not an implementation detail, it is a contract between systems written in different languages and operating at different latencies. The TypeScript cache reader mirrors the shape exactly and is written to fail open by construction:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;parseRanking&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;unknown&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;CachedProviderRanking&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;raw&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="k"&gt;typeof&lt;/span&gt; &lt;span class="n"&gt;raw&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="s1"&gt;'object'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;raw&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="nc"&gt;RawRanking&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nb"&gt;Array&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isArray&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;providers_ranked&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;providersRanked&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;providers_ranked&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;p&lt;/span&gt; &lt;span class="n"&gt;is&lt;/span&gt; &lt;span class="nc"&gt;ProviderName&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="k"&gt;typeof&lt;/span&gt; &lt;span class="n"&gt;p&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s1"&gt;'string'&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;providersRanked&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="c1"&gt;// validate scores&lt;/span&gt;
  &lt;span class="c1"&gt;// return null on any structural issue&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Every structural failure returns &lt;code&gt;null&lt;/code&gt; rather than throwing, and &lt;code&gt;null&lt;/code&gt; is the signal to fall back to deterministic provider order.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;The intelligence layer is allowed to be absent.
It is not allowed to take down a request.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Operationally, the split is clean: Databricks is responsible for learning, Upstash's Redis-protocol cache is responsible for serving the learned artifact cheaply, and the API is responsible for request execution and last-mile resilience.&lt;/p&gt;

&lt;p&gt;That separation lets each subsystem do one thing well.&lt;/p&gt;

&lt;h2&gt;
  
  
  Databricks SQL on the same governed substrate
&lt;/h2&gt;

&lt;p&gt;Databricks SQL serverless warehouses sit on the same governed catalogs and materialized outputs that power training and export. We use them for internal analytics, validation, and operational inspection, which means the numbers engineering sees, the numbers product sees, and the numbers the routing system acts on are not computed from disconnected pipelines, they are different consumers of the same governed substrate. For infrastructure teams, that is one of the real advantages of using the lakehouse model properly: analytics, orchestration, governance, and model lifecycle can share one set of contracts instead of spawning parallel stacks.&lt;/p&gt;

&lt;h2&gt;
  
  
  Fail-open as a first-class systems property
&lt;/h2&gt;

&lt;p&gt;The most important design choice in the stack is probably not the model, the ranking function, or the federation layer, it is fail-open behavior. If Upstash is unavailable, the system falls back to deterministic provider order. If the ranking key is missing or malformed, it falls back. If adaptive routing is disabled, it falls back. If Databricks compute is paused entirely, the API still serves traffic until the cache expires, and after that continues to serve through deterministic order and the normal provider failover loop.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Customer traffic is never hostage to the intelligence layer&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;This sounds obvious, but in practice many teams do not build it this way: they succeed at making routing smarter, but fail at making it safe. For us, adaptive provider selection only makes sense if it improves execution outcomes without increasing execution fragility.&lt;/p&gt;

&lt;h2&gt;
  
  
  The actual effect: regional, governed, compounding execution quality
&lt;/h2&gt;

&lt;p&gt;Once the loop is live, the effect is simple to describe and difficult to reproduce without the right architecture: every customer workload can make later workloads faster, cheaper, and more reliable. Provider attempts do not disappear after execution, they become training data; training data does not remain trapped in notebooks, it becomes ranked artifacts; ranked artifacts do not remain trapped in dashboards, they alter later execution decisions. All of it remains regionalized, governed, lineage-aware, and operationally safe. That is what "Databricks as the intelligence layer" means in our stack: not analytics beside the product, but intelligence inside the execution loop.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why we open-sourced "adaptive-island"
&lt;/h2&gt;

&lt;p&gt;We also open-sourced the engine under Apache 2.0 as &lt;a href="https://github.com/babysea-community/adaptive-island" rel="noopener noreferrer"&gt;adaptive-island&lt;/a&gt;, the reusable pattern behind this architecture. The repository packages the production-grade v0.1 contract we can support publicly: a Supabase &lt;code&gt;provider_cost_log&lt;/code&gt; source contract or adapter view, Bronze/Silver/Gold Lakeflow pipelines on Delta Lake, the &lt;code&gt;gold_provider_ranking_by_model&lt;/code&gt; scoring contract, a Gold-to-Upstash export job, cache-first Python and TypeScript SDKs, optional MLflow value-model training, a Databricks Asset Bundle deploy path, and a real-stack smoke harness for Databricks, Supabase, and Upstash. But the open-source project is not a repo dump of our internal production code, it is a generalization of the pattern for the industry.&lt;/p&gt;

&lt;p&gt;The OSS boundary is explicit. &lt;code&gt;adaptive-island&lt;/code&gt; does not ship request-path Databricks calls, stochastic online exploration, propensity logging, inverse-propensity or SNIPS promotion gates, alternate production caches, alternate warehouses, queues, search indexes, or a managed hosted service. If a capability cannot be traced to the BabySea Supabase ➜ Databricks ➜ Upstash provider-ranking loop and is not implemented in the OSS, it stays out of the public contract. An automated MLflow offline eval and promotion gate is tracked separately in the BabySea implementation guide; it is not a shipped &lt;code&gt;adaptive-island&lt;/code&gt; feature today.&lt;/p&gt;

&lt;p&gt;What the OSS packages is the production-derived pattern: real feedback from Supabase attempt logs, governed Databricks medallion transforms, deterministic Gold ranking over success, wasted-attempt, and latency behavior, Upstash cache serving, SDK payload validation, provider allowlist filtering, and deterministic fallback. Most teams building multi-provider AI systems independently rediscover the same constraints (heterogeneous APIs, unstable latency distributions, inconsistent cost surfaces, provider-specific failure modes, no principled feedback loop from real outcomes back into routing) and then over-index on hand-tuned routing logic, brittle failover code, or static preference matrices. &lt;code&gt;adaptive-island&lt;/code&gt; packages a better default: treat provider selection as a governed learning system with a cache-served serving contract and explicit fail-open behavior. That is why we believe the OSS matters, it helps the industry skip a category of avoidable reinvention.&lt;/p&gt;

&lt;h2&gt;
  
  
  What we kept, and what we gave away
&lt;/h2&gt;

&lt;p&gt;Open-sourcing the pattern does not give away the moat.&lt;/p&gt;

&lt;p&gt;The pattern is reusable, and it should be reusable. The workload data is not. Neither are the execution graph, customer demand shape, provider mix, product constraints, or regional traffic behavior.&lt;/p&gt;

&lt;p&gt;We kept the data flywheel and the customer-facing product, and the community gets the architecture, the contracts, and the operating model. That is the right boundary for this kind of infrastructure company. The proprietary advantage is not that we know medallion architecture exists, or that MLflow can register models, or that rankings can be cached, the proprietary advantage is the workload flowing through the loop and the compound execution quality that loop produces over time. &lt;code&gt;adaptive-island&lt;/code&gt; makes the pattern legible and deployable, BabySea keeps the production flywheel.&lt;/p&gt;

&lt;h2&gt;
  
  
  The broader point
&lt;/h2&gt;

&lt;p&gt;There is a larger lesson here for AI infrastructure. As the industry matures, the winning systems will not be the ones with the most wrappers or the largest configuration files, they will be the ones that convert real execution outcomes into governed, compounding control loops without making the serving path fragile. That is the problem we used Databricks to solve, the pattern we open-sourced, and the direction we think the industry should move.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>database</category>
      <category>postgres</category>
      <category>databricks</category>
    </item>
    <item>
      <title>How BabySea uses Cloudflare to secure and control execution at scale</title>
      <dc:creator>Randy Aries Saputra</dc:creator>
      <pubDate>Sun, 22 Nov 2026 03:05:38 +0000</pubDate>
      <link>https://dev.to/ariesrandy/how-babysea-uses-cloudflare-to-secure-and-control-execution-at-scale-4l2</link>
      <guid>https://dev.to/ariesrandy/how-babysea-uses-cloudflare-to-secure-and-control-execution-at-scale-4l2</guid>
      <description>&lt;p&gt;&lt;a href="https://babysea.ai" rel="noopener noreferrer"&gt;BabySea&lt;/a&gt; is execution infrastructure for generative media. That means we don't just run requests. We control how they execute across inference providers, with routing, failover, and lifecycle management.&lt;/p&gt;

&lt;p&gt;As workloads scale, the problem is not just routing requests across providers. It's ensuring invalid, abusive, or malformed requests never reach execution, where every mistake has a real cost.&lt;/p&gt;

&lt;p&gt;We use &lt;a href="https://www.cloudflare.com" rel="noopener noreferrer"&gt;Cloudflare&lt;/a&gt; as the edge control layer to enforce correctness, security, and observability before requests reach our system.&lt;/p&gt;

&lt;p&gt;This post breaks down how that works in production.&lt;/p&gt;

&lt;h2&gt;
  
  
  Architecture: edge as the first execution boundary
&lt;/h2&gt;

&lt;p&gt;BabySea runs across three regions:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;code&gt;api.us.babysea.ai&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;api.eu.babysea.ai&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;api.jp.babysea.ai&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Each region exposes the same API surface, backed by different infrastructure.&lt;/p&gt;

&lt;p&gt;Cloudflare sits in front of all entry points and acts as a:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;pre-execution control plane&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Before a request reaches our application, it must pass:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;request validation ➜ protocol enforcement&lt;/li&gt;
&lt;li&gt;WAF ➜ execution guardrail&lt;/li&gt;
&lt;li&gt;rate limiting ➜ pre-execution control&lt;/li&gt;
&lt;li&gt;managed rules ➜ threat protection&lt;/li&gt;
&lt;li&gt;API Shield ➜ contract enforcement&lt;/li&gt;
&lt;li&gt;session intelligence ➜ beyond IP&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;These controls operate as independent layers, each enforcing a different constraint before execution begins.&lt;/p&gt;

&lt;p&gt;What we are preventing is not theoretical:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;malformed requests reaching execution and wasting compute&lt;/li&gt;
&lt;li&gt;repeated invalid calls exhausting system capacity&lt;/li&gt;
&lt;li&gt;leaked API keys being used across distributed clients&lt;/li&gt;
&lt;li&gt;schema drift between providers causing runtime failures&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Each layer exists to eliminate a specific failure mode before it reaches the control plane.&lt;/p&gt;

&lt;h3&gt;
  
  
  1. Request validation as protocol enforcement
&lt;/h3&gt;

&lt;p&gt;Before applying any higher-level rules, we enforce basic protocol correctness:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;block non-HTTPS API calls&lt;/li&gt;
&lt;li&gt;block unsupported HTTP methods&lt;/li&gt;
&lt;li&gt;enforce JSON-only POST bodies&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This ensures:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;only structurally valid requests are processed further&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Without this layer, invalid requests would propagate deeper into the system and fail after resources have already been allocated.&lt;/p&gt;

&lt;h3&gt;
  
  
  2. WAF as execution guardrail
&lt;/h3&gt;

&lt;p&gt;We don't treat WAF as a security add-on. We treat it as:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;execution constraint enforcement&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;We explicitly reject malformed or suspicious patterns:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;path traversal attempts&lt;/li&gt;
&lt;li&gt;injection patterns&lt;/li&gt;
&lt;li&gt;malformed headers&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This ensures:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;only valid execution paths reach the system&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Without this layer, malformed requests would propagate into execution, where failures become expensive instead of cheap.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Abuse and scanning protection&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;We aggressively block automated scanning:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;sqlmap, nuclei, nmap, ffuf, burpsuite&lt;/li&gt;
&lt;li&gt;high-threat browser traffic is challenged&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This removes:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;background noise before it becomes load&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;Edge hardening&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;We added rules for:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;oversized Authorization headers&lt;/li&gt;
&lt;li&gt;duplicate Transfer-Encoding headers (request smuggling)&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Even if upstream systems can handle these, we block them at the edge:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;fail fast, before origin cost is incurred&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3&gt;
  
  
  3. Rate limiting as pre-execution control
&lt;/h3&gt;

&lt;p&gt;Rate limiting is not just protection. It shapes system behavior.&lt;/p&gt;

&lt;p&gt;We apply multiple layers:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Global API limit&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;x&lt;/code&gt; requests per minute per IP (pre-auth)&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Auth protection&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;x&lt;/code&gt; failed auth attempts ➜ temporary block&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Endpoint-specific limits&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;playground ➜ burst control&lt;/li&gt;
&lt;li&gt;webhook ingestion ➜ flood protection&lt;/li&gt;
&lt;li&gt;cron endpoints ➜ strict limits&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;These rules ensure:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;untrusted clients cannot dominate execution capacity&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Without rate control at the edge, invalid or abusive traffic would compete directly with legitimate execution workloads.&lt;/p&gt;

&lt;h3&gt;
  
  
  4. Managed rules as threat protection
&lt;/h3&gt;

&lt;p&gt;We leverage Cloudflare managed protections:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;OWASP rule sets&lt;/li&gt;
&lt;li&gt;Cloudflare threat intelligence&lt;/li&gt;
&lt;li&gt;automated bot detection&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This layer handles:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;known attack patterns and global threat signals&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;It allows us to absorb common threats without pushing that complexity into the application layer.&lt;/p&gt;

&lt;h3&gt;
  
  
  5. API Shield: enforcing contract at the edge
&lt;/h3&gt;

&lt;p&gt;The most important layer is API Shield.&lt;/p&gt;

&lt;p&gt;We define our API surface using OpenAPI:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;15 endpoints per region&lt;/li&gt;
&lt;li&gt;deployed across 3 regions&lt;/li&gt;
&lt;li&gt;45 operations total&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Cloudflare validates incoming requests against this schema.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What this gives us&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;invalid parameters ➜ detected immediately&lt;/li&gt;
&lt;li&gt;unknown endpoints ➜ logged as anomalies&lt;/li&gt;
&lt;li&gt;malformed requests ➜ visible before the application layer&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Without schema validation at the edge, invalid requests would only fail inside the application layer, after resources have already been consumed.&lt;/p&gt;

&lt;h3&gt;
  
  
  6. Session-based intelligence (beyond IP)
&lt;/h3&gt;

&lt;p&gt;Traditional rate limiting is IP-based. That breaks in real systems:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;shared corporate NAT&lt;/li&gt;
&lt;li&gt;distributed attackers&lt;/li&gt;
&lt;li&gt;leaked API keys&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;We track sessions using:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;code&gt;Authorization&lt;/code&gt; header as identity&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;This enables:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;per-key behavioral profiling&lt;/li&gt;
&lt;li&gt;anomaly detection&lt;/li&gt;
&lt;li&gt;request sequence tracking&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Result:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;volumetric abuse detection&lt;/li&gt;
&lt;li&gt;enumeration detection&lt;/li&gt;
&lt;li&gt;per-customer visibility&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;All enforced at the edge.&lt;/p&gt;

&lt;p&gt;IP-based control alone cannot reliably identify abuse in distributed systems.&lt;/p&gt;

&lt;p&gt;Session-level tracking allows us to enforce behavior constraints per identity, not per network.&lt;/p&gt;

&lt;h2&gt;
  
  
  Layered execution control model
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;Client Request
  ↓
Cloudflare Edge
  ├─ Request Validation (Protocol Enforcement)
  ├─ WAF (Execution Guardrail)
  ├─ Rate Limiting (Pre-Execution Control)
  ├─ Managed Rules (Threat Protection)
  ├─ API Shield (Contract Enforcement)
  ├─ Session Intelligence (Beyond IP)
  ↓
BabySea Control Plane
  ├─ Access Control
  ├─ Credit Lifecycle
  ├─ Protocol Translation
  ├─ Policy Routing
  ├─ Failover Orchestration
  ├─ Failure Handling
  ├─ Artifact Pipeline
  ├─ Event System
  ↓
Execution Layer
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The control plane defines how execution should happen. The execution layer carries it out.&lt;/p&gt;

&lt;p&gt;Each layer removes a different class of risk before it propagates.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;no single failure allows invalid or abusive execution to reach the system&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Execution is stateful, not just request-based
&lt;/h2&gt;

&lt;p&gt;Once a request passes edge validation, it enters a lifecycle that must remain consistent across providers, retries, and failures.&lt;/p&gt;

&lt;p&gt;We treat execution as a controlled state machine:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;request accepted ➜ generation created&lt;/li&gt;
&lt;li&gt;credits reserved before execution&lt;/li&gt;
&lt;li&gt;provider execution begins&lt;/li&gt;
&lt;li&gt;result confirmed inline or via webhook&lt;/li&gt;
&lt;li&gt;credits finalized as charge or refund&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This prevents critical failure classes:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;double execution across providers during failover&lt;/li&gt;
&lt;li&gt;double charge when multiple providers complete&lt;/li&gt;
&lt;li&gt;orphaned jobs when upstream systems fail&lt;/li&gt;
&lt;li&gt;inconsistent state between storage, database, and providers&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Execution is not just calling a provider.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;it is maintaining correctness across asynchronous, multi-provider systems&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;A key part of that lifecycle is ordering. We create the generation record before reserving credits, so billing and state transitions are attached to a single durable generation ID from the start.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;record&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;adminClient&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;from&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'file_assets'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;insert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;account_id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;accountId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;generation_data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;generation_provider_order&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;toProviderArray&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;providerOrder&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;generation_status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'pending'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'id, account_id, generation_id'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;single&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;reserved&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;reserveCredits&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;accountId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;model&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;record&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;generation_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;generationResolution&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That ordering matters. It avoids reserve-then-cleanup ambiguity and makes every economic event traceable to the same lifecycle record.&lt;/p&gt;

&lt;h2&gt;
  
  
  Billing correctness is enforced as an invariant
&lt;/h2&gt;

&lt;p&gt;In a multi-provider execution system, billing correctness cannot depend on good luck or a single success path.&lt;/p&gt;

&lt;p&gt;We enforce a simple invariant:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;one generation can reserve once, charge once, and refund once&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;That rule is backed by the database, not just application logic.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;UNIQUE&lt;/span&gt; &lt;span class="k"&gt;INDEX&lt;/span&gt; &lt;span class="k"&gt;IF&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;EXISTS&lt;/span&gt; &lt;span class="n"&gt;idx_credit_ledger_charge_idempotent&lt;/span&gt;
  &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;credit_ledger&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;generation_id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'charge'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;UNIQUE&lt;/span&gt; &lt;span class="k"&gt;INDEX&lt;/span&gt; &lt;span class="k"&gt;IF&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;EXISTS&lt;/span&gt; &lt;span class="n"&gt;idx_credit_ledger_refund_idempotent&lt;/span&gt;
  &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;credit_ledger&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;generation_id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'refund'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Credits are also reserved atomically. That prevents concurrent requests from both passing a balance check and spending the same balance twice.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;UPDATE&lt;/span&gt; &lt;span class="n"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;credits&lt;/span&gt;
&lt;span class="k"&gt;SET&lt;/span&gt; &lt;span class="n"&gt;tokens&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;tokens&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="n"&gt;p_tokens&lt;/span&gt;
&lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;account_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;p_account_id&lt;/span&gt;
  &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;tokens&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;=&lt;/span&gt; &lt;span class="n"&gt;p_tokens&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is what turns billing into a system property instead of a best effort.&lt;/p&gt;

&lt;h2&gt;
  
  
  Failover is controlled, not optimistic
&lt;/h2&gt;

&lt;p&gt;Failover is usually presented as a simple fallback story. In practice, it is a consistency problem.&lt;/p&gt;

&lt;p&gt;A provider can fail late. A webhook can arrive after the next provider has already been considered. Storage may already contain a completed output even when the local request path thinks it failed.&lt;/p&gt;

&lt;p&gt;We account for that explicitly.&lt;/p&gt;

&lt;p&gt;First, provider order is reordered by health so degraded providers are moved back without changing the public execution contract.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;reordered&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;sequence&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;reorderByHealth&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;baseSequence&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="n"&gt;providerOrder&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;sequence&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;', '&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then, after a failed attempt, we check storage and database state before spending money on the next provider.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;storageFiles&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;adminClient&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;storage&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;from&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'file'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;list&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sb"&gt;`${record.account_id}/${record.generation_id}`&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;storageFiles&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;storageFiles&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;step&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;predictionId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'webhook-delivered'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'succeeded'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;providerModelId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;step&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;providerModelId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;break&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is the difference between "trying another provider" and controlling a distributed execution lifecycle.&lt;/p&gt;

&lt;h2&gt;
  
  
  Provider abstraction is a contract, not a passthrough
&lt;/h2&gt;

&lt;p&gt;A multi-provider system degrades quickly if provider-specific fields leak into the public API.&lt;/p&gt;

&lt;p&gt;We keep the public contract unified and intentionally normalize provider differences into BabySea's own schema model.&lt;/p&gt;

&lt;p&gt;That includes rules like:&lt;/p&gt;

&lt;p&gt;ratio-based sizing instead of exposing raw width and height&lt;br&gt;
intersection of supported formats across active providers&lt;br&gt;
pricing dimensions modeled as core execution fields, not provider-specific knobs&lt;/p&gt;

&lt;p&gt;A simplified example:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// width: z.number().int().min(256).max(1440).optional(),&lt;/span&gt;
&lt;span class="c1"&gt;// excluded - uses ratio-based sizing, not pixel dimensions&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And at the schema level, core execution fields are ordered and enforced consistently across models:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="n"&gt;generation_prompt&lt;/span&gt;
&lt;span class="n"&gt;generation_ratio&lt;/span&gt;
&lt;span class="n"&gt;generation_output_format&lt;/span&gt;
&lt;span class="n"&gt;generation_output_number&lt;/span&gt;
&lt;span class="n"&gt;generation_input_file&lt;/span&gt;
&lt;span class="n"&gt;generation_duration&lt;/span&gt;
&lt;span class="n"&gt;generation_resolution&lt;/span&gt;
&lt;span class="n"&gt;generation_generate_audio&lt;/span&gt;
&lt;span class="n"&gt;generation_provider_order&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is what lets multiple providers behave like one execution system instead of many inconsistent APIs.&lt;/p&gt;

&lt;h2&gt;
  
  
  Edge and tenant boundaries matter as much as model execution
&lt;/h2&gt;

&lt;p&gt;Execution correctness is not only about providers. It is also about where requests are allowed to exist.&lt;/p&gt;

&lt;p&gt;Our middleware enforces API-only domains, separates marketing and dashboard surfaces, and strips headers that should never influence account identity.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;pathname&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;startsWith&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'/v1'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;NextResponse&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="nb"&gt;JSON&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;stringify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'error'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;code&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'BSE1001'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'not_found'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;message&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'Restricted access'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;404&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="s1"&gt;'Content-Type'&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'application/json'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;requestHeaders&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Headers&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="n"&gt;requestHeaders&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;delete&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'x-account-id'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;NextResponse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;next&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;requestHeaders&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That matters because execution systems are also multi-tenant systems. The edge has to enforce those trust boundaries before requests reach the control plane.&lt;/p&gt;

&lt;h2&gt;
  
  
  Execution must be protected before it begins
&lt;/h2&gt;

&lt;p&gt;In generative systems, execution is the most expensive part of the pipeline.&lt;/p&gt;

&lt;p&gt;Every invalid request that reaches execution is not just an error. It is wasted compute, wasted time, and unnecessary cost.&lt;/p&gt;

&lt;p&gt;Our design ensures that:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;invalid requests are rejected early&lt;/li&gt;
&lt;li&gt;abusive behavior is constrained before execution&lt;/li&gt;
&lt;li&gt;only valid, well-formed requests reach the control plane&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This is why edge enforcement is not optional. It is part of execution itself.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why this matters for generative media
&lt;/h2&gt;

&lt;p&gt;Generative workloads are fundamentally different:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;long-running execution&lt;/li&gt;
&lt;li&gt;high cost per request&lt;/li&gt;
&lt;li&gt;unpredictable input&lt;/li&gt;
&lt;li&gt;multi-provider dependency&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Without strict edge control:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;invalid requests waste compute&lt;/li&gt;
&lt;li&gt;abuse becomes expensive quickly&lt;/li&gt;
&lt;li&gt;provider failures cascade&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Cloudflare allows us to enforce: correctness before execution.&lt;/p&gt;

&lt;h2&gt;
  
  
  Closing
&lt;/h2&gt;

&lt;p&gt;At BabySea, execution infrastructure is not just routing and failover.&lt;/p&gt;

&lt;p&gt;It is:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;controlling what enters the system&lt;/li&gt;
&lt;li&gt;validating it before execution&lt;/li&gt;
&lt;li&gt;observing behavior at scale&lt;/li&gt;
&lt;li&gt;enforcing constraints at the edge&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Cloudflare is not just a security layer for us.&lt;/p&gt;

&lt;p&gt;It is where execution constraints begin.&lt;/p&gt;

&lt;p&gt;By the time a request reaches our system, it has already been validated, constrained, and shaped.&lt;/p&gt;

&lt;p&gt;Execution is not just what happens inside the system.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;it starts at the edge&lt;/p&gt;
&lt;/blockquote&gt;

</description>
      <category>ai</category>
      <category>security</category>
      <category>database</category>
      <category>cloudflare</category>
    </item>
    <item>
      <title>How BabySea built strict request normalization with JSON Schema and TypeScript</title>
      <dc:creator>Randy Aries Saputra</dc:creator>
      <pubDate>Sun, 22 Nov 2026 03:01:35 +0000</pubDate>
      <link>https://dev.to/ariesrandy/how-babysea-built-strict-request-normalization-with-json-schema-and-typescript-3o4c</link>
      <guid>https://dev.to/ariesrandy/how-babysea-built-strict-request-normalization-with-json-schema-and-typescript-3o4c</guid>
      <description>&lt;p&gt;Multi-provider AI is not a collection of SDK wrappers. It is translation.&lt;/p&gt;

&lt;p&gt;That distinction matters because image and video providers do not agree on names, defaults, formats, safety controls, duration semantics, asset limits, or payload shape. One provider calls a field &lt;code&gt;aspect_ratio&lt;/code&gt;; another calls it &lt;code&gt;aspect&lt;/code&gt;; another wants width and height. One provider accepts &lt;code&gt;jpg&lt;/code&gt;; another returns &lt;code&gt;jpeg&lt;/code&gt;. One provider treats moderation as an enabled flag; another treats it as a disabled flag; another wants a tolerance level. One provider exposes audio as a boolean; another makes audio part of a model tier.&lt;/p&gt;

&lt;p&gt;If those differences leak into the public API, the product becomes a provider wrapper instead of a control plane.&lt;/p&gt;

&lt;p&gt;At &lt;a href="https://babysea.ai" rel="noopener noreferrer"&gt;BabySea&lt;/a&gt;, the customer-facing request shape is kept separate from provider-native payloads. Provider contracts are recorded, refined into one strict public schema, normalized once, and only then converted into provider dialects. That boundary is the pattern we open-sourced as &lt;a href="https://github.com/babysea-community/rosetta-bridge" rel="noopener noreferrer"&gt;rosetta-bridge&lt;/a&gt;: a JSON + TypeScript normalization primitive for teams building one API across many inference providers.&lt;/p&gt;

&lt;h2&gt;
  
  
  Schema drift is the first reliability bug
&lt;/h2&gt;

&lt;p&gt;Provider failover usually breaks before the network call. It breaks when a request that was valid for the first provider is not actually valid for the fallback provider.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Customer request
  -&amp;gt; Provider A accepts 16:9 + jpg + moderation=false
  -&amp;gt; Provider A fails
  -&amp;gt; Provider B only supports 1:1 + jpeg + a different moderation field
  -&amp;gt; fallback changes semantics or fails after dispatch
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The bad version of this system discovers the mismatch after the request has already passed validation. The better version refuses to expose the mismatch in the first place.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Request normalization is not a cleanup step. It is the invariant that makes failover, pricing, persistence, and debugging possible.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;The mistake is to treat provider schemas as customer schemas. Provider docs describe what a vendor accepts. A product schema describes what the product promises. Those are related, but they are not the same contract.&lt;/p&gt;

&lt;h2&gt;
  
  
  Provider docs are raw material, not the public API
&lt;/h2&gt;

&lt;p&gt;BabySea's production schema pipeline starts with a simple rule: the raw provider shape must stay raw. Provider names, defaults, bounds, enum values, and exclusions are recorded from provider documentation without pretending they are already customer-safe.&lt;/p&gt;

&lt;p&gt;Then we define the refined customer-facing schema. Internally, that schema uses BabySea &lt;code&gt;generation_*&lt;/code&gt; fields, strict validation, declared defaults, capability intersections, and explicit conversion into provider-native payloads. The same discipline appears across the production &lt;code&gt;refine-schema.ts&lt;/code&gt; files: provider-specific details are preserved, but customers see one stable contract.&lt;/p&gt;

&lt;p&gt;Conceptually, the production path looks like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Provider docs / API reference
  -&amp;gt; raw provider schema notes
  -&amp;gt; strict BabySea refine schema
  -&amp;gt; canonical generation input
  -&amp;gt; toProviderInput(...) + provider-specific option mapping
  -&amp;gt; provider-native payload
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;rosetta-bridge&lt;/code&gt; generalizes that boundary with public-neutral terms:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;BabySea production concept&lt;/th&gt;
&lt;th&gt;Public OSS concept&lt;/th&gt;
&lt;th&gt;Preserved invariant&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Raw provider schema&lt;/td&gt;
&lt;td&gt;Provider contract notes&lt;/td&gt;
&lt;td&gt;Provider-native names stay outside customer input.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Strict &lt;code&gt;generation_*&lt;/code&gt; refine schema&lt;/td&gt;
&lt;td&gt;Strict &lt;code&gt;request_*&lt;/code&gt; field specs&lt;/td&gt;
&lt;td&gt;Unknown fields fail before dispatch.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;createModelConverter(...)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Bridge definition&lt;/td&gt;
&lt;td&gt;One product schema owns defaults and supported values.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Shared input fields&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;fields.core&lt;/code&gt; + &lt;code&gt;mapCore(...)&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Product-level fields are visible before provider mapping.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Provider-specific &lt;code&gt;specificSchema&lt;/code&gt; mapping&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;fields.options&lt;/code&gt; + &lt;code&gt;mapOptions(...)&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Tuning knobs map after core fields.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Structured provider exception&lt;/td&gt;
&lt;td&gt;&lt;code&gt;mapStructured(...)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Nested payload assembly is explicit, not accidental.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Canonical generation envelope&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;normalization-result.v1&lt;/code&gt; envelope&lt;/td&gt;
&lt;td&gt;Debug/test output has one comparable shape.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The names are different because the OSS package is meant for the community, not only for BabySea. BabySea can use &lt;code&gt;generation_*&lt;/code&gt; internally. A portable primitive should expose neutral &lt;code&gt;request_*&lt;/code&gt; fields.&lt;/p&gt;

&lt;h2&gt;
  
  
  The open-source stack is JSON + TypeScript
&lt;/h2&gt;

&lt;p&gt;The public stack is deliberately small:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;JSON Schema Draft 2020-12&lt;/strong&gt; versions portable bridge manifests and normalization-result envelopes.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;TypeScript&lt;/strong&gt; declares field specs, validates requests, applies defaults, and runs adapter functions.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Your backend&lt;/strong&gt; owns authentication, persistence, billing, queues, rate limits, provider SDK calls, webhooks, and routing.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;That last line is part of the contract. &lt;code&gt;rosetta-bridge&lt;/code&gt; is not a hosted inference gateway, not a provider router, not a billing system, and not BabySea's private model catalog. It is the schema-hardening boundary that should run after your application has authenticated the caller and before your application dispatches to a provider.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Application backend
  │  auth, billing, persistence, queues, routing, provider SDKs live here
  ▼
rosetta-bridge
  │  strict JSON + TypeScript normalization boundary
  ▼
Provider-native payload
  │
  ▼
Application-owned provider client
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;blockquote&gt;
&lt;p&gt;If a behavior is outside the JSON + TypeScript normalization boundary, it is outside the &lt;code&gt;rosetta-bridge&lt;/code&gt; package.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;That scoping is what makes the primitive reusable. Different teams will choose different databases, billing providers, queues, SDKs, and routing systems. The normalization invariant is the part they should not have to rediscover.&lt;/p&gt;

&lt;h2&gt;
  
  
  One public request, many provider dialects
&lt;/h2&gt;

&lt;p&gt;The public request should be boring:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"request_prompt"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"a glass penguin on a bridge"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"request_aspect_ratio"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"16:9"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"request_output_format"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"jpg"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Provider payloads are allowed to be weird:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"prompt"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"a glass penguin on a bridge"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"aspect_ratio"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"16:9"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"format"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"jpg"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"text"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"a glass penguin on a bridge"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"aspect"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"16:9"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"output_format"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"jpeg"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The product promise is not that every provider speaks the same dialect. The product promise is that customers do not need to know which dialect will run their request.&lt;/p&gt;

&lt;p&gt;In &lt;code&gt;rosetta-bridge&lt;/code&gt;, the public request vocabulary is lowercase snake-case &lt;code&gt;request_*&lt;/code&gt;. Common core fields include:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Public field&lt;/th&gt;
&lt;th&gt;Why it is core&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;request_prompt&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The creative prompt is provider-agnostic.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;request_aspect_ratio&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Customers choose product ratios, not provider pixel formulas.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;request_output_format&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Public formats stay stable while adapters handle provider aliases.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;request_output_count&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Output count affects product behavior and may affect price.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;request_input_assets&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Asset limits must be safe before dispatch.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;request_duration_seconds&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Duration can affect video price and routing.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;request_resolution&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Resolution can affect price, policy, or provider eligibility.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;request_audio&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Audio mode can affect cost and provider payload shape.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;request_provider_order&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The request can carry a public provider-order preference or sentinel.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Option fields are public tuning knobs, such as &lt;code&gt;request_seed&lt;/code&gt;, &lt;code&gt;request_negative_prompt&lt;/code&gt;, &lt;code&gt;request_enhance_prompt&lt;/code&gt;, and &lt;code&gt;request_moderation&lt;/code&gt;. They are still public fields, but they map after the core product fields.&lt;/p&gt;

&lt;h2&gt;
  
  
  Defaults are part of the product contract
&lt;/h2&gt;

&lt;p&gt;Provider defaults are dangerous because they vary by vendor and can change without matching your product policy.&lt;/p&gt;

&lt;p&gt;If one provider defaults to permissive moderation and another defaults to strict moderation, the same customer request can produce different behavior depending on failover. If one provider defaults to high resolution and another defaults to low resolution, the same request can change cost. If one provider defaults to audio and another does not, the customer may not understand what they bought.&lt;/p&gt;

&lt;p&gt;So the default belongs in the public field spec, not in the adapter.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"schema_version"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"bridge-definition.v1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"model_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"example/media-model"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"supported_providers"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"provider_a"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"provider_b"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"core_fields"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"request_prompt"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nl"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"string"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"required"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"minLength"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"request_aspect_ratio"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nl"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"enum"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"values"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"1:1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"16:9"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"default"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"1:1"&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"request_output_format"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nl"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"enum"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"values"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"png"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"jpg"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"default"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"png"&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That JSON manifest is portable because it contains the public contract, not executable provider functions. Provider adapters live in trusted TypeScript or JavaScript modules because a mapping function is code.&lt;/p&gt;

&lt;h2&gt;
  
  
  Intersections beat unions
&lt;/h2&gt;

&lt;p&gt;The most tempting schema is the union of every provider capability. It is also the schema most likely to break failover.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Provider A supports: 1:1, 16:9, 9:16, png, jpg
Provider B supports: 1:1, 16:9, png, jpeg

Unsafe public union:        1:1, 16:9, 9:16, png, jpg, jpeg
Safer public intersection:  1:1, 16:9, png, jpg after product-level aliasing
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The public schema should expose what every registered provider path can deliver for that bridge. If a provider cannot deliver a capability, the bridge should not accept that capability for a workload that may fall back to that provider.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;rosetta-bridge&lt;/code&gt; includes helper functions for simple intersections and aspect-ratio ordering, but the invariant is not automatic magic. The adapter author still has to understand provider semantics and choose the product contract deliberately.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;A public schema is not a list of everything any provider can do. It is a list of what the product can safely promise.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;That is why &lt;code&gt;request_input_assets&lt;/code&gt;, &lt;code&gt;request_duration_seconds&lt;/code&gt;, &lt;code&gt;request_resolution&lt;/code&gt;, and &lt;code&gt;request_audio&lt;/code&gt; are core fields. They are not just provider options; they can affect price, policy, routing eligibility, and fallback safety.&lt;/p&gt;

&lt;h2&gt;
  
  
  Pricing-sensitive dimensions stay visible before dispatch
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;rosetta-bridge&lt;/code&gt; does not bill customers. It still preserves the production invariant that cost-sensitive choices must be visible before provider dispatch.&lt;/p&gt;

&lt;p&gt;In BabySea's production schema pipeline, video duration, resolution, generated audio, input files, and output count are not hidden inside provider-specific mappers when they affect execution policy or pricing. They are part of the canonical request shape that the surrounding application can inspect.&lt;/p&gt;

&lt;p&gt;The OSS version follows the same rule:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nc"&gt;RosettaBridge&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;enhancePromptToMode&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;moderationToDisableBoolean&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;sharedMediaFields&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'rosetta-bridge'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;bridge&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;RosettaBridge&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;schemaVersion&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'bridge-definition.v1'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;modelId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'example/video-model'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;supportedProviders&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'provider_a'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'provider_b'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;providerOrder&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'provider_a'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'provider_b'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;fields&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;core&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;sharedMediaFields&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;supportedAspectRatios&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'1:1'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'16:9'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;supportedFormats&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'mp4'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;durationValues&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;5&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;supportedResolutions&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'720p'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'1080p'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;defaultResolution&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'720p'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;supportsAudio&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;maxInputAssets&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;providerOrders&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
        &lt;span class="s1"&gt;'fastest'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="s1"&gt;'provider_a,provider_b'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="s1"&gt;'provider_b,provider_a'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;defaultProviderOrder&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'fastest'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;options&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;request_enhance_prompt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'enum'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;values&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'off'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'standard'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'fast'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="k"&gt;default&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'off'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;request_moderation&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'boolean'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;request_seed&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'integer'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;providers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;provider_a&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;mapCore&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;prompt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;request_prompt&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;aspect_ratio&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;request_aspect_ratio&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;duration&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="sb"&gt;`${String(input.request_duration_seconds)}s`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;resolution&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;request_resolution&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;generate_audio&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;request_audio&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;mapOptions&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;prompt_optimizer&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;enhancePromptToMode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;disable_safety_checker&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;moderationToDisableBoolean&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;seed&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;request_seed&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;provider_b&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;mapCore&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;request_prompt&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;ratio&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;request_aspect_ratio&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;seconds&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;request_duration_seconds&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;quality&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;request_resolution&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;audio&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;request_audio&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;mapOptions&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;enhancement_mode&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;enhancePromptToMode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;safety&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;request_moderation&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="s1"&gt;'enabled'&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'permissive'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;seed_value&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;request_seed&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The surrounding application can price, authorize, queue, or route from the canonical core fields before it ever calls a provider SDK. The adapter can still rename or type-convert those fields for each provider, but it does not hide the product decision.&lt;/p&gt;

&lt;h2&gt;
  
  
  Core mapping and option mapping are separate on purpose
&lt;/h2&gt;

&lt;p&gt;Provider adapters have two normal mapping functions:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;provider_payload = {
  ...mapCore(full_normalized_request),
  ...mapOptions(full_normalized_request),
}
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;mapCore(...)&lt;/code&gt; handles product-level fields. &lt;code&gt;mapOptions(...)&lt;/code&gt; handles tuning fields. Both receive the full normalized request because provider payloads often combine concepts. For example, a provider detail string may depend on both aspect ratio and quality; a safety setting may depend on a public moderation flag plus a provider-specific convention.&lt;/p&gt;

&lt;p&gt;The separation is not about limiting what code can read. It is about making the adapter readable and reviewable.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Core fields
  -&amp;gt; prompt, ratio, format, input assets, duration, resolution, audio

Option fields
  -&amp;gt; seed, negative prompt, enhance prompt, moderation, guidance scale
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;When a provider requires a nested object or array, the adapter uses &lt;code&gt;mapStructured(...)&lt;/code&gt; as an explicit exception:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;providerC&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;mapStructured&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
      &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'text'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;request_prompt&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'asset'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Array&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isArray&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;request_input_assets&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
          &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;request_input_assets&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
          &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That exception is important because nested payload assembly is a different shape of work. It should be visible in review, not buried inside a flat mapper.&lt;/p&gt;

&lt;h2&gt;
  
  
  Prompt enhancement and moderation are semantic fields
&lt;/h2&gt;

&lt;p&gt;Prompt enhancement and moderation are classic schema-drift traps because providers expose the same product idea through incompatible switches.&lt;/p&gt;

&lt;p&gt;One provider may want:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"enhance_prompt"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Another may want:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"prompt_optimizer_mode"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"standard"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Another may want:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"prompt_optimizer"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"mode"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"fast"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The customer should not have to learn those differences. The public schema can expose &lt;code&gt;request_enhance_prompt: "off" | "standard" | "fast"&lt;/code&gt;, and adapters translate it through helper functions.&lt;/p&gt;

&lt;p&gt;Moderation has the same problem. Some providers expose &lt;code&gt;disable_safety_checker&lt;/code&gt;; others expose &lt;code&gt;enable_safety_checker&lt;/code&gt;; others expose a tolerance field where the most permissive value is the opposite end of the enum. &lt;code&gt;rosetta-bridge&lt;/code&gt; keeps the public concept as &lt;code&gt;request_moderation: boolean&lt;/code&gt; and gives adapter helpers for the common translations.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;A boolean is not always semantically the same boolean. Provider adapters need to encode whether the provider field enables safety, disables safety, or maps into a tolerance scale.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;That is the same reason BabySea production keeps prompt enhancement and moderation as canonical public concepts before provider conversion.&lt;/p&gt;

&lt;h2&gt;
  
  
  Canonical envelopes make debugging possible
&lt;/h2&gt;

&lt;p&gt;Normalization should produce something inspectable. &lt;code&gt;rosetta-bridge&lt;/code&gt; can emit a &lt;code&gt;normalization-result.v1&lt;/code&gt; envelope with the schema version, model ID, provider, provider order, canonical input, provider payload, and timestamp.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"schema_version"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"normalization-result.v1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"model_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"example/media-model"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"provider"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"provider_b"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"provider_order"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"provider_a"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"provider_b"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"canonical_input"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"request_prompt"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"a glass penguin on a bridge"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"request_aspect_ratio"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"16:9"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"request_output_format"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"jpg"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"request_moderation"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"provider_payload"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"text"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"a glass penguin on a bridge"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"aspect"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"16:9"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"output_format"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"jpeg"&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"generated_at"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"2026-05-07T00:00:00.000Z"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That envelope is useful in tests, CLI smoke checks, docs, and application logs. It also makes omitted option fields explicit when you want complete canonical shapes. A compact object is possible, but complete envelopes make comparison easier across providers and versions.&lt;/p&gt;

&lt;p&gt;BabySea's hosted product can persist canonical generation inputs inside its own systems. The OSS primitive does not ship that persistence layer; it emits the normalized shape so your application can decide what to store.&lt;/p&gt;

&lt;h2&gt;
  
  
  Fail before dispatch
&lt;/h2&gt;

&lt;p&gt;The bridge should run before queues, provider SDKs, and webhooks enter the picture. If a request is malformed, the failure should happen while the application can still return a clean validation error.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;rosetta-bridge&lt;/code&gt; rejects:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;missing required fields&lt;/li&gt;
&lt;li&gt;unknown public fields&lt;/li&gt;
&lt;li&gt;unsupported enum or number values&lt;/li&gt;
&lt;li&gt;invalid defaults in bridge definitions&lt;/li&gt;
&lt;li&gt;invalid integer or numeric bounds&lt;/li&gt;
&lt;li&gt;unsupported providers&lt;/li&gt;
&lt;li&gt;bad URL values in &lt;code&gt;url&lt;/code&gt; and &lt;code&gt;url-array&lt;/code&gt; fields&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;URL validation is intentionally HTTP(S)-only at the schema boundary. That is not a full SSRF defense; it is the local type and scheme invariant. A production backend should still enforce trusted origins, redirect handling, private-network protections, file-size limits, content-type checks, and fetch isolation when it dereferences customer-supplied URLs.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;normalize(input)
  -&amp;gt; reject unknown request field
  -&amp;gt; reject unsupported enum
  -&amp;gt; reject non-HTTP(S) URL
  -&amp;gt; apply declared defaults
  -&amp;gt; emit canonical input
  -&amp;gt; map to provider payload
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;blockquote&gt;
&lt;p&gt;Provider dispatch should consume a normalized request, not discover whether a request was valid.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;That is the same systems lesson as credit settlement and adaptive routing: put the invariant at the boundary where failure is still cheap.&lt;/p&gt;

&lt;h2&gt;
  
  
  The &lt;code&gt;fastest&lt;/code&gt; sentinel is not routing by itself
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;request_provider_order: "fastest"&lt;/code&gt; is a public sentinel. In BabySea production, the surrounding execution control plane can resolve that idea through private routing layers before dispatch. In the OSS primitive, the bridge does not include those routing layers.&lt;/p&gt;

&lt;p&gt;Instead, the bridge can expand the sentinel to the configured concrete provider order, or your backend can replace it with its own provider decision before calling &lt;code&gt;toProviderInput(...)&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;request_provider_order = "fastest"
  -&amp;gt; host application may resolve provider order
  -&amp;gt; bridge validates the resulting provider choice
  -&amp;gt; adapter emits provider-native payload
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That keeps the public request vocabulary compatible with smarter host applications without pretending the normalization package is a ranking service.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why this became OSS
&lt;/h2&gt;

&lt;p&gt;Every multi-provider AI company eventually builds some version of this layer.&lt;/p&gt;

&lt;p&gt;They start with one provider. Then they add a fallback. Then they add a second model family. Then they discover that defaults differ, safety flags invert, output formats alias, duration fields change type, input asset limits do not match, nested payloads break flat mappers, and public API fields have accidentally become provider-specific.&lt;/p&gt;

&lt;p&gt;By the time the system works, the important part is not the provider SDK wrapper. The important part is the normalization contract.&lt;/p&gt;

&lt;p&gt;That is why we open-sourced &lt;code&gt;rosetta-bridge&lt;/code&gt; under Apache 2.0. The repository packages the reusable part of BabySea's schema-hardening pattern: JSON Schema contracts, TypeScript field specs, strict unknown-field rejection, declared defaults, provider adapter boundaries, prompt and moderation helper semantics, URL validation, canonical normalization envelopes, CLI smoke paths, and fixture-driven examples.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;The pattern should be reusable. The provider catalog, customer data, routing intelligence, billing system, credentials, and operating graph remain outside the primitive.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;The boundary is deliberate. We are not publishing BabySea's private provider catalog or hosted execution code. We are publishing the shape of a schema discipline that should not need to be rebuilt from scratch by every team integrating multiple AI providers.&lt;/p&gt;

&lt;h2&gt;
  
  
  The broader point
&lt;/h2&gt;

&lt;p&gt;As AI infrastructure matures, the winning systems will not be the ones with the most provider wrappers. They will be the ones with the clearest contracts between customer intent, product policy, provider capability, execution routing, and settlement.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;rosetta-bridge&lt;/code&gt; owns one of those contracts: customer intent becomes a strict canonical request, and that request becomes a provider-native payload only after validation.&lt;/p&gt;

&lt;p&gt;That sounds small, but it is the layer that prevents silent schema drift from turning into broken failover, inconsistent pricing, unpredictable moderation, and impossible debugging. JSON Schema gives the public contract a versioned shape. TypeScript gives adapters a safe executable boundary. Together, they turn provider chaos into one request the product can actually promise.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>json</category>
      <category>typescript</category>
      <category>tutorial</category>
    </item>
    <item>
      <title>How BabySea built atomic credit settlement on Stripe and Postgres</title>
      <dc:creator>Randy Aries Saputra</dc:creator>
      <pubDate>Sun, 22 Nov 2026 02:56:12 +0000</pubDate>
      <link>https://dev.to/ariesrandy/how-babysea-built-atomic-credit-settlement-on-stripe-and-postgres-306o</link>
      <guid>https://dev.to/ariesrandy/how-babysea-built-atomic-credit-settlement-on-stripe-and-postgres-306o</guid>
      <description>&lt;p&gt;AI generation billing is not checkout. It is settlement.&lt;/p&gt;

&lt;p&gt;That distinction matters because generative media does not behave like a normal SaaS seat, a normal API call, or a normal one-time purchase. A customer can start an image or video generation, the accepted cost must be reserved immediately, the provider can take seconds or minutes to finish, the webhook can arrive late or twice, and the process can crash between reservation and terminal settlement. Weeks later, the underlying &lt;a href="https://stripe.com" rel="noopener noreferrer"&gt;Stripe&lt;/a&gt; payment may need a separate refund or dispute workflow outside the credit ledger.&lt;/p&gt;

&lt;p&gt;If the billing system treats that lifecycle as a simple payment event, it eventually leaks money or user trust.&lt;/p&gt;

&lt;p&gt;At &lt;a href="https://babysea.ai" rel="noopener noreferrer"&gt;BabySea&lt;/a&gt;, Stripe moves money. &lt;a href="https://www.postgresql.org" rel="noopener noreferrer"&gt;PostgreSQL&lt;/a&gt; enforces settlement integrity. The application coordinates the flow, but it does not hold the invariant. That boundary is the core of our credit system and the reason we open-sourced the reusable pattern as &lt;a href="https://github.com/babysea-community/ledger-fortress" rel="noopener noreferrer"&gt;ledger-fortress&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why AI billing is a settlement problem
&lt;/h2&gt;

&lt;p&gt;Stripe is excellent at the payment side of the system: subscriptions, checkout, invoices, disputes, refunds, webhook delivery, and reconciliation around real money movement. But an AI generation platform still needs a separate operating ledger for spendable credits because customer spend happens asynchronously after the Stripe payment.&lt;/p&gt;

&lt;p&gt;The hard part is not adding credits after an invoice is paid. The hard part is preserving correctness across every state transition after that.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Stripe payment succeeds
  -&amp;gt; credits granted
  -&amp;gt; generation cost is computed from accepted inputs
  -&amp;gt; generation reserves credits
  -&amp;gt; provider runs async workload
  -&amp;gt; generation succeeds, fails, times out, or is canceled
  -&amp;gt; charge or refund records the terminal outcome
  -&amp;gt; Stripe refund or dispute policy stays outside the ledger package
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each arrow is a failure boundary. If any boundary relies on a best-effort application check, the system is already fragile.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;The payment processor should not be asked
to understand every generation state.

The generation system should not be asked
to act like a bank.

The ledger is the contract between them.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Stripe moves money, Postgres enforces credits
&lt;/h2&gt;

&lt;p&gt;The architecture is intentionally boring.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Stripe
  -&amp;gt; invoice.paid
  -&amp;gt; checkout.session.completed
  -&amp;gt; checkout.session.async_payment_succeeded

Postgres
  -&amp;gt; plans
  -&amp;gt; credits
  -&amp;gt; credit_ledger
  -&amp;gt; credit_alert_settings
  -&amp;gt; credit_alert_log

Application
  -&amp;gt; maps Stripe customers to accounts
  -&amp;gt; starts generation only after reserve succeeds
  -&amp;gt; calls add, reserve, charge, or refund
  -&amp;gt; handles Stripe refunds and disputes outside the credit ledger
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Stripe is the source of truth for external payment events. Postgres is the source of truth for internal spendable balance and settlement history. The application is deliberately thin at the invariant boundary.&lt;/p&gt;

&lt;p&gt;That separation matters because Stripe webhooks are asynchronous by design. They can be retried. They can arrive after local state has moved forward. They can describe a payment that affects credits the customer has already spent. The database must make every replay and every ordering safe.&lt;/p&gt;

&lt;h2&gt;
  
  
  The two ledgers
&lt;/h2&gt;

&lt;p&gt;There are really two ledgers in this system.&lt;/p&gt;

&lt;p&gt;The first is Stripe's ledger of money movement: invoices, checkout sessions, refunds, and disputes.&lt;/p&gt;

&lt;p&gt;The second is the credit ledger pattern we package in &lt;code&gt;ledger-fortress&lt;/code&gt;: reserves, charges, refunds, and additive grants.&lt;/p&gt;

&lt;p&gt;They are connected, but they are not the same thing.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;The mistake is to collapse payment state
and workload state into one abstraction.

Payments settle money.
Workloads settle credits.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In &lt;code&gt;ledger-fortress&lt;/code&gt;, the core storage shape is small:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;TABLE&lt;/span&gt; &lt;span class="n"&gt;credits&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;account_id&lt;/span&gt; &lt;span class="kt"&gt;uuid&lt;/span&gt; &lt;span class="k"&gt;PRIMARY&lt;/span&gt; &lt;span class="k"&gt;KEY&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;credits&lt;/span&gt; &lt;span class="kt"&gt;numeric&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="kc"&gt;NULL&lt;/span&gt; &lt;span class="k"&gt;DEFAULT&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt; &lt;span class="k"&gt;CHECK&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;credits&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;updated_at&lt;/span&gt; &lt;span class="kt"&gt;timestamptz&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="kc"&gt;NULL&lt;/span&gt; &lt;span class="k"&gt;DEFAULT&lt;/span&gt; &lt;span class="nb"&gt;now&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;TABLE&lt;/span&gt; &lt;span class="n"&gt;credit_ledger&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="kt"&gt;uuid&lt;/span&gt; &lt;span class="k"&gt;PRIMARY&lt;/span&gt; &lt;span class="k"&gt;KEY&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;account_id&lt;/span&gt; &lt;span class="kt"&gt;uuid&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="kc"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;type&lt;/span&gt; &lt;span class="kt"&gt;text&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="kc"&gt;NULL&lt;/span&gt; &lt;span class="k"&gt;CHECK&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;type&lt;/span&gt; &lt;span class="k"&gt;IN&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'reserve'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'charge'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'refund'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'add'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;amount&lt;/span&gt; &lt;span class="kt"&gt;numeric&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="kc"&gt;NULL&lt;/span&gt; &lt;span class="k"&gt;CHECK&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;amount&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;balance_after&lt;/span&gt; &lt;span class="kt"&gt;numeric&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="kc"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;generation_id&lt;/span&gt; &lt;span class="kt"&gt;text&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;model&lt;/span&gt; &lt;span class="kt"&gt;text&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="kt"&gt;text&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;created_at&lt;/span&gt; &lt;span class="kt"&gt;timestamptz&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="kc"&gt;NULL&lt;/span&gt; &lt;span class="k"&gt;DEFAULT&lt;/span&gt; &lt;span class="nb"&gt;now&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;credits&lt;/code&gt; table holds the current spendable balance in its &lt;code&gt;credits&lt;/code&gt; column. &lt;code&gt;credit_ledger&lt;/code&gt; is the immutable audit trail. The balance can be recomputed and inspected from the ledger, but runtime execution reads the current balance because generation gating has to be fast.&lt;/p&gt;

&lt;h2&gt;
  
  
  The hot path is one atomic update
&lt;/h2&gt;

&lt;p&gt;The most important query in the system is not a Stripe call. It is the reservation.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;UPDATE&lt;/span&gt; &lt;span class="n"&gt;credits&lt;/span&gt;
&lt;span class="k"&gt;SET&lt;/span&gt; &lt;span class="n"&gt;credits&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;credits&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="n"&gt;p_credits&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;updated_at&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;now&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;account_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;p_account_id&lt;/span&gt;
  &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;credits&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;=&lt;/span&gt; &lt;span class="n"&gt;p_credits&lt;/span&gt;
&lt;span class="k"&gt;RETURNING&lt;/span&gt; &lt;span class="n"&gt;credits&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That one statement answers the only question the generation path needs to ask before dispatching work: can this account afford this generation right now?&lt;/p&gt;

&lt;p&gt;There is no separate read. There is no application lock. There is no distributed transaction. If two requests race, PostgreSQL serializes the updates. The loser sees the new balance and fails if there is not enough left.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;The generation starts after
the database has already
made the affordability decision atomically.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The lifecycle then becomes explicit:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;reserve_credits
  -&amp;gt; deduct balance and write reserve ledger entry

charge_credits
  -&amp;gt; confirm successful generation, log-only because reserve already deducted

refund_credits
  -&amp;gt; return reserved credits when generation fails or is canceled

add_credits
  -&amp;gt; grant paid Stripe invoice or checkout credits additively
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is the pattern we use for async generation: compute the accepted cost before reserve, deduct before spending provider capacity, then confirm or refund after the workload reaches a terminal state.&lt;/p&gt;

&lt;h2&gt;
  
  
  Idempotency belongs in the database
&lt;/h2&gt;

&lt;p&gt;Webhook retries are not exceptional. They are part of the system. The ledger has to treat them as normal traffic.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;ledger-fortress&lt;/code&gt; enforces idempotency with unique partial indexes, not handler memory:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;UNIQUE&lt;/span&gt; &lt;span class="k"&gt;INDEX&lt;/span&gt; &lt;span class="n"&gt;idx_credit_ledger_charge_idempotent&lt;/span&gt;
  &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;credit_ledger&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;generation_id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'charge'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;UNIQUE&lt;/span&gt; &lt;span class="k"&gt;INDEX&lt;/span&gt; &lt;span class="n"&gt;idx_credit_ledger_refund_idempotent&lt;/span&gt;
  &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;credit_ledger&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;generation_id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'refund'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;UNIQUE&lt;/span&gt; &lt;span class="k"&gt;INDEX&lt;/span&gt; &lt;span class="n"&gt;idx_credit_ledger_add_idempotent&lt;/span&gt;
  &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;credit_ledger&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;account_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;description&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'add'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;UNIQUE&lt;/span&gt; &lt;span class="k"&gt;INDEX&lt;/span&gt; &lt;span class="n"&gt;idx_credit_ledger_reserve_idempotent&lt;/span&gt;
  &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;credit_ledger&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;generation_id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'reserve'&lt;/span&gt; &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;generation_id&lt;/span&gt; &lt;span class="k"&gt;IS&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="kc"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This means duplicate success callbacks, duplicate failure callbacks, duplicate Stripe invoice webhooks, duplicate credit pack webhooks, and duplicate reservation retries all collapse into safe no-ops.&lt;/p&gt;

&lt;p&gt;The application can retry. Stripe can retry. Cron can retry. The database decides whether a state transition already happened.&lt;/p&gt;

&lt;h2&gt;
  
  
  Turning Stripe payments into credits
&lt;/h2&gt;

&lt;p&gt;The Stripe side of the system is narrow by design.&lt;/p&gt;

&lt;p&gt;The webhook route starts by verifying Stripe's signature against the raw request body. Parsed JSON is not enough because signature verification depends on the exact bytes Stripe sent.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;payload&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;text&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;signature&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'stripe-signature'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;event&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;verifyStripeSignature&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;stripe&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;payload&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;signature&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;STRIPE_WEBHOOK_SECRET&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;After verification, &lt;code&gt;invoice.paid&lt;/code&gt; grants subscription credits, while &lt;code&gt;checkout.session.completed&lt;/code&gt; or &lt;code&gt;checkout.session.async_payment_succeeded&lt;/code&gt; grants paid one-time credit packs. By default, both paths convert cents to credits and call &lt;code&gt;add_credits&lt;/code&gt; with an idempotency key derived from the Stripe object.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;credits&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;invoice&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;amount_paid&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;idempotencyKey&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="sb"&gt;`invoice:${invoice.id}`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;fortress&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addCredits&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;accountId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;amount&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;credits&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;idempotencyKey&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;idempotencyKey&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For credit packs, BabySea production keys the grant from its internal order ID. The standalone OSS helper uses the Stripe payment intent when present, otherwise the checkout session ID, because those IDs are available in a portable Stripe integration:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;idempotencyKey&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="sb"&gt;`order:${paymentIntentId ?? session.id}`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That small convention is what makes Stripe retries harmless. If the same invoice or checkout completion is delivered twice, the second insert hits the &lt;code&gt;add&lt;/code&gt; idempotency index and does not grant credits again.&lt;/p&gt;

&lt;p&gt;It also gives credits rollover semantics. A renewal adds to the existing balance. It never resets the balance.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;previous balance: 3.500
invoice.paid:    +29.000
new balance:     32.500
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That detail is critical for usage-based products with credit packs. A customer who buys a one-time pack should not lose it on subscription renewal.&lt;/p&gt;

&lt;h2&gt;
  
  
  Stale checkout sessions are a real edge case
&lt;/h2&gt;

&lt;p&gt;Stripe Checkout sessions can outlive the state that created them. A customer can start a credit pack checkout, cancel or lose the subscription that made them eligible, and then complete the checkout later.&lt;/p&gt;

&lt;p&gt;The production pattern is to guard credit pack redemption at webhook time, not only at session creation time.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;hasActiveSubscription&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;active&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;hasActiveSubscription&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;accountId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;active&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;handled&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;action&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'skipped_no_subscription'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The payment event is still observed. Credits are not granted unless the account is still eligible. That turns a subtle stale-session problem into an explicit operational case.&lt;/p&gt;

&lt;h2&gt;
  
  
  Generation settlement: reserve, then confirm
&lt;/h2&gt;

&lt;p&gt;The generation path is separate from the payment path.&lt;/p&gt;

&lt;p&gt;Before dispatching an async generation, the application computes and reserves the accepted cost:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;acceptedCost&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;priceGeneration&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;reserved&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;fortress&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;reserve&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;accountId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;generationId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;amount&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;acceptedCost&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;model&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;reserved&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'insufficient_credits'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;runGeneration&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;When the workload succeeds, the system calls &lt;code&gt;charge&lt;/code&gt;. Because the reservation already deducted the balance, charge is a confirmation event.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;fortress&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;charge&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;accountId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;generationId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;amount&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;acceptedCost&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;model&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;When the workload fails or is canceled, the system calls &lt;code&gt;refund&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;fortress&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;refund&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;accountId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;generationId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;amount&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;acceptedCost&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;model&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This split keeps the critical path tight. The request path does one balance mutation. The async path records the terminal outcome.&lt;/p&gt;

&lt;h2&gt;
  
  
  Out-of-order callbacks are where billing systems break
&lt;/h2&gt;

&lt;p&gt;The most dangerous failures happen when two truthful events arrive in the wrong order.&lt;/p&gt;

&lt;p&gt;Example: a timeout path refunds a reservation, then a late success callback arrives. If &lt;code&gt;charge&lt;/code&gt; is log-only and does not notice the prior refund, the customer gets the output for free.&lt;/p&gt;

&lt;p&gt;So &lt;code&gt;charge_credits&lt;/code&gt; checks for an existing refund under lock. If a refund already returned credits, charge re-deducts the reserved amount before logging success. If the balance cannot cover the late correction, it returns &lt;code&gt;FALSE&lt;/code&gt; instead of marking the generation charged, leaving the application to retry, pause the account, or escalate the case.&lt;/p&gt;

&lt;p&gt;The opposite ordering matters too. If a generation has already been charged, a late refund path must not return credits.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;IF&lt;/span&gt; &lt;span class="k"&gt;EXISTS&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;credit_ledger&lt;/span&gt;
  &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;generation_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;p_generation_id&lt;/span&gt;
    &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'charge'&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;THEN&lt;/span&gt;
  &lt;span class="k"&gt;RETURN&lt;/span&gt; &lt;span class="kc"&gt;FALSE&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;END&lt;/span&gt; &lt;span class="k"&gt;IF&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That guard prevents the deadly sequence: reserve, success webhook, charge, crash recovery, refund, free output.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Out-of-order events are not bugs in an async system.
They are part of tthe environment the ledger must be
designed to survive.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Pricing boundary: compute before reserve
&lt;/h2&gt;

&lt;p&gt;Generative media is often priced from user-selected parameters such as model, duration, output count, resolution, and audio mode. In the current BabySea credit implementation and the current &lt;code&gt;ledger-fortress&lt;/code&gt; OSS surface, that cost is computed before &lt;code&gt;reserve_credits&lt;/code&gt; runs.&lt;/p&gt;

&lt;p&gt;That boundary keeps terminal settlement simple: reserve, charge, and refund all use the same accepted amount for the generation.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;acceptedCost&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;priceGeneration&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'video-5s'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;durationSeconds&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;5&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;resolution&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'720p'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;fortress&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;reserve&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;accountId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;generationId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;amount&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;acceptedCost&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'video-5s'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;fortress&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;charge&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;accountId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;generationId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;amount&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;acceptedCost&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'video-5s'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;ledger-fortress&lt;/code&gt; deliberately does not ship &lt;code&gt;settle_credits&lt;/code&gt;, true-up ledger entries, negative balances, or uncollectible debt tracking. If a product needs a different terminal pricing policy, it should be implemented as an explicit extension and tested separately from this BabySea-derived OSS surface.&lt;/p&gt;

&lt;p&gt;That is the important accounting property in the current package: the workload settles through explicit &lt;code&gt;charge&lt;/code&gt; or &lt;code&gt;refund&lt;/code&gt; transitions using the reserved amount, and never depends on silently adjusting the cost after reserve.&lt;/p&gt;

&lt;h2&gt;
  
  
  Stripe refunds and disputes stay outside the package
&lt;/h2&gt;

&lt;p&gt;When a Stripe payment is refunded or disputed, the credits granted by that payment may already be gone. The policy response is product-specific: support workflow, account review, refund handling, dispute evidence, or a custom extension.&lt;/p&gt;

&lt;p&gt;The current BabySea credit implementation does not automatically convert &lt;code&gt;charge.refunded&lt;/code&gt; or &lt;code&gt;charge.dispute.created&lt;/code&gt; into credit deductions, so the current &lt;code&gt;ledger-fortress&lt;/code&gt; OSS package does not ship &lt;code&gt;clawback_credits&lt;/code&gt;, debt entries, or dispute handlers.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;switch&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;case&lt;/span&gt; &lt;span class="s1"&gt;'invoice.paid'&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;grantSubscriptionCredits&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;event&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;case&lt;/span&gt; &lt;span class="s1"&gt;'checkout.session.completed'&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="k"&gt;case&lt;/span&gt; &lt;span class="s1"&gt;'checkout.session.async_payment_succeeded'&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;grantCreditPackCredits&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;event&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;default&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;handled&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The boundary is intentional. &lt;code&gt;ledger-fortress&lt;/code&gt; handles the credit grants and generation settlement invariants that BabySea actually runs. Refund and dispute deductions remain outside the public package unless they are implemented and validated as a separate flow.&lt;/p&gt;

&lt;h2&gt;
  
  
  Crash recovery closes the ghost-reservation hole
&lt;/h2&gt;

&lt;p&gt;The slowest leak in async billing is the ghost reservation: credits are reserved, the generation is dispatched, the process dies, and no terminal callback is ever recorded.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;ledger-fortress&lt;/code&gt; treats crash recovery as a replayable settlement path.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="nf"&gt;find_orphaned_reservations&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;5&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That function finds reservations older than a safety window with no matching &lt;code&gt;charge&lt;/code&gt; or &lt;code&gt;refund&lt;/code&gt; settlement. The recovery worker calls &lt;code&gt;refund_credits&lt;/code&gt; for each orphan. Because &lt;code&gt;refund_credits&lt;/code&gt; no-ops if a charge or refund already exists, recovery can overlap safely with late provider callbacks.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;cron finds orphan
  -&amp;gt; refund_credits
  -&amp;gt; if already charged, no-op
  -&amp;gt; if already refunded, no-op
  -&amp;gt; otherwise return credits
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is another place where correctness belongs in the ledger rather than the scheduler. The cron can miss a cycle. It can run twice. It can overlap with webhooks. The database still decides the valid terminal state.&lt;/p&gt;

&lt;h2&gt;
  
  
  Alerts should not block settlement
&lt;/h2&gt;

&lt;p&gt;Low-balance alerts are useful, but they should never be on the critical path for generation. In &lt;code&gt;ledger-fortress&lt;/code&gt;, alert checks are intentionally fire-and-forget.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;void&lt;/span&gt; &lt;span class="n"&gt;fortress&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;checkAlerts&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;accountId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each threshold fires once per descent and resets when balance recovers. The alert check runs outside the generation gating path, and the alert system can fail without blocking reservation, charge, refund, or Stripe reconciliation.&lt;/p&gt;

&lt;p&gt;That boundary keeps billing correctness separate from notification delivery.&lt;/p&gt;

&lt;h2&gt;
  
  
  Security: the ledger cannot be a public table
&lt;/h2&gt;

&lt;p&gt;Credit tables are not application cache. They are financial state. The open-source migrations enforce that posture.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;ledger-fortress&lt;/code&gt; enables row-level security on every table, revokes anonymous and authenticated table access, and runs mutating operations through &lt;code&gt;SECURITY DEFINER&lt;/code&gt; functions with a locked &lt;code&gt;search_path&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;ALTER&lt;/span&gt; &lt;span class="k"&gt;TABLE&lt;/span&gt; &lt;span class="n"&gt;credits&lt;/span&gt; &lt;span class="no"&gt;ENABLE&lt;/span&gt; &lt;span class="k"&gt;ROW&lt;/span&gt; &lt;span class="no"&gt;LEVEL&lt;/span&gt; &lt;span class="no"&gt;SECURITY&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;REVOKE&lt;/span&gt; &lt;span class="k"&gt;ALL&lt;/span&gt; &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;credits&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;anon&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;REVOKE&lt;/span&gt; &lt;span class="k"&gt;ALL&lt;/span&gt; &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;credits&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;authenticated&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;ALTER&lt;/span&gt; &lt;span class="k"&gt;FUNCTION&lt;/span&gt; &lt;span class="nf"&gt;reserve_credits&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;uuid&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;numeric&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;text&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;text&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="no"&gt;SECURITY&lt;/span&gt; &lt;span class="no"&gt;DEFINER&lt;/span&gt;
  &lt;span class="k"&gt;SET&lt;/span&gt; &lt;span class="n"&gt;search_path&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;pg_catalog&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;public&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The public contract is not direct table mutation. The public contract is the set of functions that preserve the invariants.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why this became OSS
&lt;/h2&gt;

&lt;p&gt;Every AI generation company eventually rebuilds this system.&lt;/p&gt;

&lt;p&gt;They start with Stripe Checkout. Then they add credits. Then they add async generation. Then they discover duplicate webhooks, out-of-order callbacks, stale checkout sessions, crash recovery, low-balance notifications, audit requirements, and the need to keep refund/dispute policy separate from the credit ledger invariant.&lt;/p&gt;

&lt;p&gt;By the time it works, the system is no longer checkout. It is a settlement engine.&lt;/p&gt;

&lt;p&gt;That is why we open-sourced &lt;code&gt;ledger-fortress&lt;/code&gt; under Apache 2.0. The repository packages the generalized pattern: PostgreSQL migrations, a TypeScript SDK, a core Python SDK, Stripe webhook helpers, JSON Schemas, crash recovery, credit alerts, and local examples.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;The pattern should be reusable.
The customer data, payment history,
workload mix, fraud signals, and
production operating graph remain BabySea's.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The boundary is deliberate. We are not publishing BabySea's customer ledger. We are publishing the shape of a settlement system that should not need to be rediscovered by every team building async AI infrastructure.&lt;/p&gt;

&lt;h2&gt;
  
  
  The broader point
&lt;/h2&gt;

&lt;p&gt;As AI products move from demos to production, billing moves from payment collection to workload settlement. The systems that survive will treat money movement, credit movement, workload state, and reconciliation as separate but connected contracts.&lt;/p&gt;

&lt;p&gt;Stripe is the right primitive for external payments. Postgres is the right primitive for local settlement invariants. The application should coordinate, not improvise.&lt;/p&gt;

&lt;p&gt;That is the lesson behind &lt;code&gt;ledger-fortress&lt;/code&gt;: every generation settles, every retry is safe, every grant, reserve, charge, and refund is auditable, and the balance never depends on the hope that callbacks arrive once, in order, at the perfect time.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>database</category>
      <category>stripe</category>
      <category>postgres</category>
    </item>
    <item>
      <title>Routing is not a fallback</title>
      <dc:creator>Randy Aries Saputra</dc:creator>
      <pubDate>Sun, 22 Nov 2026 02:41:40 +0000</pubDate>
      <link>https://dev.to/ariesrandy/routing-is-not-a-fallback-k95</link>
      <guid>https://dev.to/ariesrandy/routing-is-not-a-fallback-k95</guid>
      <description>&lt;p&gt;Most systems treat routing as a safety mechanism:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;try provider A
if it fails ➜ use provider B
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This model breaks under production conditions. Because failure is not an exception. It is part of the system.&lt;/p&gt;

&lt;h2&gt;
  
  
  A generation request is not a function call
&lt;/h2&gt;

&lt;p&gt;A typical assumption:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;input ➜ provider ➜ output&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;What actually happens:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;request is authenticated and rate-limited&lt;/li&gt;
&lt;li&gt;input is validated against model-specific schemas&lt;/li&gt;
&lt;li&gt;provider order is resolved (user-defined or model default)&lt;/li&gt;
&lt;li&gt;providers are filtered by capability&lt;/li&gt;
&lt;li&gt;execution order is reordered based on health&lt;/li&gt;
&lt;li&gt;credits are reserved before execution&lt;/li&gt;
&lt;li&gt;state is persisted before any provider call&lt;/li&gt;
&lt;li&gt;provider is executed (async, polling, webhook, or hybrid)&lt;/li&gt;
&lt;li&gt;output is reconciled across storage and database&lt;/li&gt;
&lt;li&gt;billing is finalized&lt;/li&gt;
&lt;li&gt;webhook is delivered&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This is not a call. It is a &lt;strong&gt;stateful execution system&lt;/strong&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Routing is decided before execution
&lt;/h2&gt;

&lt;p&gt;In the system, routing is not reactive. It is computed before the first provider runs.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;baseSequence&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;providerOrder&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;split&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;','&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;p&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;providerLookup&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;providerLookup&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;reordered&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;sequence&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;reorderByHealth&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;baseSequence&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two important properties:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Provider order is &lt;strong&gt;model-aware&lt;/strong&gt;
&lt;/li&gt;
&lt;li&gt;Execution order is &lt;strong&gt;health-aware&lt;/strong&gt;
&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;This means:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;the "first provider" is not fixed&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Routing is already dynamic before execution begins.&lt;/p&gt;

&lt;h2&gt;
  
  
  Execution is not linear
&lt;/h2&gt;

&lt;p&gt;A naive system assumes:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;A ➜ fail ➜ B ➜ fail ➜ C ➜ success&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;The real system does not work like this.&lt;/p&gt;

&lt;p&gt;Execution is &lt;strong&gt;interleaved with external signals&lt;/strong&gt;:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;provider responses&lt;/li&gt;
&lt;li&gt;webhook deliveries&lt;/li&gt;
&lt;li&gt;storage writes&lt;/li&gt;
&lt;li&gt;cancellation acknowledgements&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A provider can:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;fail locally&lt;/li&gt;
&lt;li&gt;succeed remotely&lt;/li&gt;
&lt;li&gt;deliver output after timeout&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;So the system introduces a &lt;strong&gt;grace period&lt;/strong&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;sleep&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;GRACE_PERIOD&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;files&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;storage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;list&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;path&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;files&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="c1"&gt;// previous provider actually succeeded&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is critical.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;success is not determined by the API response
it is determined by state convergence
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Storage becomes the source of truth
&lt;/h2&gt;

&lt;p&gt;Providers are inconsistent. They disagree on:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;status&lt;/li&gt;
&lt;li&gt;timing&lt;/li&gt;
&lt;li&gt;completion signals&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;So the system does not trust them. Instead, it treats:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;storage + database = ground truth&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Before failing over, it checks:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;storage for output files&lt;/li&gt;
&lt;li&gt;DB for final status&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Only if both confirm failure does it continue. This prevents:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;double execution&lt;/li&gt;
&lt;li&gt;overwriting valid outputs&lt;/li&gt;
&lt;li&gt;inconsistent state transitions&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Failover is part of execution, not after it
&lt;/h2&gt;

&lt;p&gt;Before moving to the next provider, the system does:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;attempt cancellation of current prediction&lt;/li&gt;
&lt;li&gt;log cost outcome&lt;/li&gt;
&lt;li&gt;mark failover state in DB&lt;/li&gt;
&lt;li&gt;wait for webhook resolution
&lt;/li&gt;
&lt;/ul&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;cancelResult&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;cancelProviderPrediction&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;predictionId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;model&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;update&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;generation_failover_in_progress&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That flag is not cosmetic. It prevents webhook handlers from:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;marking the job as failed&lt;/li&gt;
&lt;li&gt;refunding credits prematurely&lt;/li&gt;
&lt;li&gt;firing incorrect events&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Failover is coordinated across:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;execution&lt;/li&gt;
&lt;li&gt;storage&lt;/li&gt;
&lt;li&gt;billing&lt;/li&gt;
&lt;li&gt;webhooks&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Cost is tightly coupled with routing
&lt;/h2&gt;

&lt;p&gt;Before execution:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;reserved&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;reserveCredits&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;After execution:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;success ➜ &lt;code&gt;chargeCredits&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;failure ➜ &lt;code&gt;refundCredits&lt;/code&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;During execution:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;each provider attempt is logged&lt;/li&gt;
&lt;li&gt;outcomes are resolved:

&lt;ul&gt;
&lt;li&gt;&lt;code&gt;used&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;failed&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;cancelled&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Routing directly affects:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;how many providers run&lt;/li&gt;
&lt;li&gt;how long they run&lt;/li&gt;
&lt;li&gt;whether they are canceled in time&lt;/li&gt;
&lt;/ul&gt;

&lt;blockquote&gt;
&lt;p&gt;routing decisions are financial decisions&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Providers are fundamentally different systems
&lt;/h2&gt;

&lt;p&gt;Each provider requires a different execution model (image):&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;a href="https://bfl.ai" rel="noopener noreferrer"&gt;Black Forest Labs&lt;/a&gt; ➜ async job + polling + signed URL retrieval&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://www.byteplus.com" rel="noopener noreferrer"&gt;BytePlus&lt;/a&gt; ➜ synchronous response + manual finalization&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://www.cloudflare.com" rel="noopener noreferrer"&gt;Cloudflare&lt;/a&gt; ➜ edge-based synchronous execution + direct response&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://fal.ai" rel="noopener noreferrer"&gt;Fal&lt;/a&gt; ➜ queue submit + polling + webhook-backed completion&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://openai.com" rel="noopener noreferrer"&gt;OpenAI&lt;/a&gt; ➜ synchronous generation/edit response + manual finalization&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://replicate.com" rel="noopener noreferrer"&gt;Replicate&lt;/a&gt; ➜ async submit + polling + webhook-backed completion&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://runwayml.com" rel="noopener noreferrer"&gt;Runway&lt;/a&gt; ➜ async task + polling + file download&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Even basic concepts differ:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;what "completed" means&lt;/li&gt;
&lt;li&gt;how output is delivered&lt;/li&gt;
&lt;li&gt;how errors are structured&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;So routing is not switching endpoints. It is:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;mapping multiple execution models into a single lifecycle&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  The real abstraction is execution
&lt;/h2&gt;

&lt;p&gt;The system exposes:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;code&gt;generation_id&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;generation_status&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;generation_provider_order&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;generation_prediction_id&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;generation_output_file&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Not:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;provider APIs&lt;/li&gt;
&lt;li&gt;provider schemas&lt;/li&gt;
&lt;li&gt;provider lifecycle&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The user interacts with:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;a single execution state machine&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Everything else is internal.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why fallback logic fails
&lt;/h2&gt;

&lt;p&gt;If routing is implemented as fallback:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;providers execute without coordination&lt;/li&gt;
&lt;li&gt;cancellation cannot be enforced consistently&lt;/li&gt;
&lt;li&gt;cost leaks across retries&lt;/li&gt;
&lt;li&gt;valid results are overwritten by later failures&lt;/li&gt;
&lt;li&gt;duplicate or incorrect events are emitted&lt;/li&gt;
&lt;li&gt;idempotency breaks under real load&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Fallback assumes providers behave predictably. They do not.&lt;/p&gt;

&lt;h2&gt;
  
  
  What this system actually is
&lt;/h2&gt;

&lt;p&gt;Not a proxy. Not a router. It is a stateful execution engine coordinating unreliable providers. Routing is one function inside that system.&lt;/p&gt;

&lt;h2&gt;
  
  
  Closing
&lt;/h2&gt;

&lt;p&gt;Routing is not:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;what happens when something fails&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;It is:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;how execution is defined under uncertainty&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;If a system depends on:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;a primary provider&lt;/li&gt;
&lt;li&gt;a clean failure signal&lt;/li&gt;
&lt;li&gt;a simple retry&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;it will fail in production. Because the real system is not:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;request ➜ response&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;It is:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;multiple inconsistent signals converging into a final state&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;And routing is the mechanism that makes that convergence possible.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>tutorial</category>
      <category>opensource</category>
      <category>architecture</category>
    </item>
    <item>
      <title>Moderation is not one field</title>
      <dc:creator>Randy Aries Saputra</dc:creator>
      <pubDate>Sun, 22 Nov 2026 02:38:31 +0000</pubDate>
      <link>https://dev.to/ariesrandy/moderation-is-not-one-field-2ka5</link>
      <guid>https://dev.to/ariesrandy/moderation-is-not-one-field-2ka5</guid>
      <description>&lt;p&gt;When people discuss moderation in generative media, they often describe it as if there is a single standard control: turn safety on, turn safety off, maybe adjust one tolerance value.&lt;/p&gt;

&lt;p&gt;That is not how real model interfaces work.&lt;/p&gt;

&lt;p&gt;In practice, moderation is exposed through a scattered set of fields that vary from model to model. One model may expose &lt;code&gt;disable_safety_checker&lt;/code&gt;. Another may expose &lt;code&gt;enable_safety_checker&lt;/code&gt;. Another may use &lt;code&gt;safety_tolerance&lt;/code&gt; as a number. Another may use the same field as a string enum. Some models add &lt;code&gt;safety_filter_level&lt;/code&gt;. Others expose a separate &lt;code&gt;moderation&lt;/code&gt; mode. Some combine several of these. Some expose only one.&lt;/p&gt;

&lt;p&gt;The result is that moderation is not a clean capability. It is a fragmented interface.&lt;/p&gt;

&lt;p&gt;Because the inconsistency is not in documentation, it is in the interface itself.&lt;/p&gt;

&lt;h2&gt;
  
  
  The real interface is inconsistent
&lt;/h2&gt;

&lt;p&gt;A model can expose moderation through fields like these:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="n"&gt;disable_safety_checker&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;boolean&lt;/span&gt;
&lt;span class="n"&gt;enable_safety_checker&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;boolean&lt;/span&gt;
&lt;span class="n"&gt;safety_tolerance&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;number&lt;/span&gt;
&lt;span class="n"&gt;safety_tolerance&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;
&lt;span class="n"&gt;safety_filter_level&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;
&lt;span class="n"&gt;moderation&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The inconsistency is not superficial. It exists at multiple levels at once.&lt;/p&gt;

&lt;p&gt;First, the field names conflict. &lt;code&gt;disable_safety_checker&lt;/code&gt; and &lt;code&gt;enable_safety_checker&lt;/code&gt; represent opposite polarity. A strict moderation intent may require &lt;code&gt;false&lt;/code&gt; in one model and &lt;code&gt;true&lt;/code&gt; in another.&lt;/p&gt;

&lt;p&gt;Second, the types conflict. &lt;code&gt;safety_tolerance&lt;/code&gt; may be numeric in one model and a string enum in another.&lt;/p&gt;

&lt;p&gt;Third, the semantics conflict. A boolean switch is not equivalent to a tolerance range, and neither is equivalent to a policy level such as &lt;code&gt;block_low_and_above&lt;/code&gt; or a moderation mode such as &lt;code&gt;auto&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Fourth, availability is inconsistent. Some models expose one moderation field, some expose several, some expose combinations that have to be aligned manually.&lt;/p&gt;

&lt;p&gt;This means there is no stable moderation surface at the model layer.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why direct exposure fails
&lt;/h2&gt;

&lt;p&gt;A pass-through design looks simple: expose every raw field and let developers choose what they want.&lt;/p&gt;

&lt;p&gt;That design fails immediately in a multi-model system. It pushes all inconsistency upward. The application now has to know which model expects inverted booleans, which one expects a string tolerance, which one wants a numeric range, and which one needs multiple moderation fields coordinated together.&lt;/p&gt;

&lt;p&gt;At that point, the API is no longer abstracting anything.&lt;/p&gt;

&lt;p&gt;It is just forwarding fragmentation.&lt;/p&gt;

&lt;p&gt;A useful abstraction has to preserve intent. The same request should mean the same thing regardless of which model is ultimately selected.&lt;/p&gt;

&lt;h2&gt;
  
  
  The BabySea abstraction
&lt;/h2&gt;

&lt;p&gt;BabySea defines a single control for moderation intent:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="n"&gt;generation_moderation&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;boolean&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The meaning is intentionally simple.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kc"&gt;true&lt;/span&gt;  &lt;span class="c1"&gt;// moderation ON  ➜ strict/safe&lt;/span&gt;
&lt;span class="kc"&gt;false&lt;/span&gt; &lt;span class="c1"&gt;// moderation OFF ➜ permissive&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is the only moderation input that matters at the BabySea layer. Everything else becomes derived behavior.&lt;/p&gt;

&lt;p&gt;That choice is important. The goal is not to expose every moderation knob a model happens to have. The goal is to define one stable contract for the user, then translate it into model-specific configuration behind the scenes.&lt;/p&gt;

&lt;h2&gt;
  
  
  Mapping opposite boolean semantics
&lt;/h2&gt;

&lt;p&gt;The most obvious inconsistency is polarity.&lt;/p&gt;

&lt;p&gt;Some models represent moderation through a disabling field. In that case, strict moderation must invert the value:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;moderationToDisableBoolean&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;SharedInputSchema&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;boolean&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;val&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;generation_moderation&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="kt"&gt;boolean&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;val&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;val&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Other models represent moderation through an enabling field. In that case, the mapping is direct:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;moderationToEnableBoolean&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;SharedInputSchema&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;boolean&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;generation_moderation&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="kt"&gt;boolean&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This looks trivial, but it is exactly the kind of inconsistency that creates subtle bugs when raw fields are exposed directly. A user should not need to know whether a model thinks in terms of enabling safety or disabling it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Moderation is often multi-field, not single-field
&lt;/h2&gt;

&lt;p&gt;The harder problem is that moderation often cannot be expressed through one value alone. A single strict or permissive intent may need to drive several fields at once.&lt;/p&gt;

&lt;p&gt;In BabySea, the same &lt;code&gt;generation_moderation&lt;/code&gt; input can map into:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;disable_safety_checker&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;moderationToDisableBoolean&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;safety_tolerance&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;moderationToSafetyTolerance&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;rawField&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;safety_filter_level&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;moderationToSafetyFilterLevel&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;moderation&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;moderationToModerationString&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Or, for another model surface:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;enable_safety_checker&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;moderationToEnableBoolean&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;safety_tolerance&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;moderationToSafetyToleranceString&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;rawField&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is the key point: moderation is not normalized by renaming one field. It is normalized by coordinating several unrelated fields so they all represent the same user intent.&lt;/p&gt;

&lt;p&gt;If moderation is strict, all derived values must point in the strict direction. If moderation is permissive, all derived values must point in the permissive direction. That coordination is the actual complexity of moderation.&lt;/p&gt;

&lt;h2&gt;
  
  
  Tolerance cannot be hardcoded
&lt;/h2&gt;

&lt;p&gt;Tolerance is where many implementations become fragile. It is tempting to hardcode something like "strict means 1, permissive means 6."&lt;/p&gt;

&lt;p&gt;That only works until a model uses a different range, or exposes tolerance as an enum instead of a number.&lt;/p&gt;

&lt;p&gt;BabySea avoids that by deriving bounds from the schema itself:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;extractSafetyBounds&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;schema&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ZodTypeAny&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;min&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;number&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;max&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;number&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="n"&gt;inner&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ZodTypeAny&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;schema&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;while&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;inner&lt;/span&gt; &lt;span class="k"&gt;instanceof&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ZodOptional&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="n"&gt;inner&lt;/span&gt; &lt;span class="k"&gt;instanceof&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ZodDefault&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;inner&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;
      &lt;span class="n"&gt;inner&lt;/span&gt; &lt;span class="k"&gt;instanceof&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ZodOptional&lt;/span&gt;
        &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="n"&gt;inner&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;unwrap&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;inner&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ZodDefault&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ZodTypeAny&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;_def&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;innerType&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;inner&lt;/span&gt; &lt;span class="k"&gt;instanceof&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ZodNumber&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="n"&gt;min&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="n"&gt;max&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;6&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;check&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;inner&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;_def&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;checks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Array&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;kind&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;number&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;checks&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;check&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;kind&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s1"&gt;'min'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;min&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;check&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;check&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;kind&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s1"&gt;'max'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;max&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;check&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;min&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;max&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;inner&lt;/span&gt; &lt;span class="k"&gt;instanceof&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ZodEnum&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;nums&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;inner&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;_def&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;values&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;Number&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sort&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;a&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;min&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;nums&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;max&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;nums&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;nums&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;min&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;max&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;6&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This matters because it makes moderation schema-driven rather than assumption-driven. The converter does not guess the valid strict and permissive bounds. It reads them from the actual field definition.&lt;/p&gt;

&lt;p&gt;From there, the mapping becomes deterministic:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;moderationToSafetyTolerance&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;SharedInputSchema&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;rawField&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ZodTypeAny&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;number&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;val&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;generation_moderation&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="kt"&gt;boolean&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;val&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;min&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;max&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;extractSafetyBounds&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;rawField&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;val&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="n"&gt;min&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;max&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And for models that expect the same concept as a string:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;moderationToSafetyToleranceString&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;SharedInputSchema&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;rawField&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ZodTypeAny&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;val&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;generation_moderation&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="kt"&gt;boolean&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;val&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;min&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;max&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;extractSafetyBounds&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;rawField&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;val&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="nb"&gt;String&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;min&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;String&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;max&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That is a much stronger design than hardcoding model assumptions into business logic. It lets the schema remain the source of truth.&lt;/p&gt;

&lt;h2&gt;
  
  
  Semantic moderation fields also need normalization
&lt;/h2&gt;

&lt;p&gt;Not all moderation controls are numeric. Some are semantic levels.&lt;/p&gt;

&lt;p&gt;BabySea maps those too:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;moderationToSafetyFilterLevel&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;SharedInputSchema&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;val&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;generation_moderation&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="kt"&gt;boolean&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;val&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;val&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="s1"&gt;'block_low_and_above'&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'block_only_high'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;moderationToModerationString&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;SharedInputSchema&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;val&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;generation_moderation&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="kt"&gt;boolean&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;val&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;val&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="s1"&gt;'auto'&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'low'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;These strings are model-level implementation details. They should not leak into the public API as if they were universal moderation concepts. They are just one more representation that has to be normalized.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the public contract becomes
&lt;/h2&gt;

&lt;p&gt;Once all of these mappings are in place, the public moderation surface becomes stable.&lt;/p&gt;

&lt;p&gt;The user sees this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="n"&gt;generation_moderation&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Internally, one model may receive:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"disable_safety_checker"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"safety_tolerance"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"safety_filter_level"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"block_low_and_above"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"moderation"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"auto"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Another may receive:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"enable_safety_checker"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"safety_tolerance"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"1"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The raw fields differ. The types differ. The polarity differs. But the intent is identical.&lt;/p&gt;

&lt;p&gt;That is the value of normalization.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why this matters
&lt;/h2&gt;

&lt;p&gt;This is not just about moderation. It reflects a broader reality of generative media infrastructure: model interfaces are not stable, not uniform, and not designed around shared abstractions.&lt;/p&gt;

&lt;p&gt;If an orchestration layer simply forwards raw fields, it inherits that fragmentation and passes it directly to every customer.&lt;/p&gt;

&lt;p&gt;A pass-through API is a transport layer for inconsistency.&lt;/p&gt;

&lt;p&gt;If the goal is to provide a real platform contract, the inconsistency has to be absorbed above the model layer.&lt;/p&gt;

&lt;p&gt;Moderation is one of the clearest examples because the fragmentation is visible immediately: enable versus disable, number versus string, tolerance versus policy mode. But the same pattern shows up in many other parts of the stack.&lt;/p&gt;

&lt;p&gt;The correct response is not to document the inconsistency better. The correct response is to normalize it above the model layer.&lt;/p&gt;

&lt;h2&gt;
  
  
  Conclusion
&lt;/h2&gt;

&lt;p&gt;Moderation is not a field. It is not a toggle. It is part of execution itself.&lt;/p&gt;

&lt;p&gt;If safety is defined only at the interface, it will break under real-world conditions; across providers, across models, and across time.&lt;/p&gt;

&lt;p&gt;What has to be built is not validation at the edge, but enforcement throughout the lifecycle.&lt;/p&gt;

&lt;p&gt;At BabySea, moderation is not something attached to a request.&lt;/p&gt;

&lt;p&gt;It is something the system carries through execution.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>tutorial</category>
      <category>opensource</category>
      <category>architecture</category>
    </item>
    <item>
      <title>Launching BabyChain: durable image and video model chains on AWS Aurora and Vercel</title>
      <dc:creator>Randy Aries Saputra</dc:creator>
      <pubDate>Sat, 13 Jun 2026 01:34:00 +0000</pubDate>
      <link>https://dev.to/ariesrandy/launching-babychain-durable-image-and-video-model-chains-on-aws-aurora-and-vercel-1p5h</link>
      <guid>https://dev.to/ariesrandy/launching-babychain-durable-image-and-video-model-chains-on-aws-aurora-and-vercel-1p5h</guid>
      <description>&lt;p&gt;Today we are launching &lt;strong&gt;BabyChain&lt;/strong&gt;: a self-hosted canvas studio and durable chain API for image and video model workflows.&lt;/p&gt;

&lt;p&gt;The short version is this: BabyChain lets you design a ComfyUI-style media chain on a canvas, then call that same chain from product code as &lt;code&gt;POST /api/v1/chains/runs&lt;/code&gt;. Every step executes through provider APIs with server-side credentials, every state transition persists to &lt;a href="https://aws.amazon.com/rds/aurora" rel="noopener noreferrer"&gt;AWS Aurora&lt;/a&gt;, and &lt;a href="https://vercel.com" rel="noopener noreferrer"&gt;Vercel&lt;/a&gt; functions stay stateless.&lt;/p&gt;

&lt;p&gt;The product has one invariant: &lt;strong&gt;every output becomes the next input.&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Website: &lt;a href="https://babychain.babysea.live" rel="noopener noreferrer"&gt;https://babychain.babysea.live&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;GitHub: &lt;a href="https://github.com/babysea-community/babychain" rel="noopener noreferrer"&gt;https://github.com/babysea-community/babychain&lt;/a&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you run model chains on a local GPU workbench today, BabyChain is the version of that workflow you can deploy, call from a backend, and keep forever. The canvas is not a demo shell. It is a visual editor on top of the same durable contract your application calls.&lt;/p&gt;




&lt;h2&gt;
  
  
  Why we built it: canvas workflows are not production infrastructure
&lt;/h2&gt;

&lt;p&gt;Real generative media work is rarely one model call. It is an image model feeding an image-to-video model, often with a refine step in the middle and a video-to-video step at the end. Canvas tools made that composable, but most of them are creative workbenches. The workflow lives inside a UI, expects a local GPU or a managed model runtime, and does not naturally become an authenticated API that another product can call.&lt;/p&gt;

&lt;p&gt;We kept hitting the same wall in our own projects: the moment a visual workflow needed to become &lt;em&gt;product infrastructure&lt;/em&gt; (authenticated, retryable, callable from a queue, safe to expose to another backend), we had to rewrite it as glue code.&lt;/p&gt;

&lt;p&gt;BabyChain's design goal was to make that distance zero.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Design the chain on a canvas. Call the same chain from your backend. Those should not be two different systems.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  What ships today
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Multi-flow canvas studio.&lt;/strong&gt; Many independent image → video flows side by side on one permanent workspace, with autosave and a library of saved chains plus their results.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;57 image and video models&lt;/strong&gt; across Alibaba Cloud, Black Forest Labs, BytePlus, Google, OpenAI, and Runway, for &lt;strong&gt;78,948 valid chain combinations&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Schema-true node cards, powered by Semantic Lady.&lt;/strong&gt; Every card's fields, enum options, ranges, and defaults are generated from that model's schema, so the UI cannot offer a parameter the API would reject.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;BYOK execution.&lt;/strong&gt; Provider keys live in the server environment, never in the browser and never in caller requests. Caller apps authenticate with BabyChain API keys.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Durable runs on Aurora.&lt;/strong&gt; Ordered steps, provider request ids, generation ids, outputs, failures, callbacks, and a timeline are all persisted. One signed callback delivers the terminal run when a webhook URL is supplied.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;a href="https://github.com/babysea-community/semantic-lady" rel="noopener noreferrer"&gt;Semantic Lady&lt;/a&gt; became necessary because BabyChain supports two execution worlds. In BabySea mode, the BabySea SDK already gives us a normalized &lt;code&gt;generation_*&lt;/code&gt; contract. In BYOK mode, BabyChain talks directly to provider APIs, and every provider brings its own schema vocabulary. Semantic Lady is the local SDK that gives BYOK mode a real schema layer: model metadata, field definitions, enum options, defaults, and constraints that the canvas and API can trust before a provider request is sent.&lt;/p&gt;

&lt;h2&gt;
  
  
  Self-host it in an afternoon
&lt;/h2&gt;

&lt;p&gt;BabyChain is Apache-2.0 and built to be deployed, not hosted by us:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;git clone https://github.com/babysea-community/babychain.git
&lt;span class="nb"&gt;cd&lt;/span&gt; babychain &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; pnpm install --frozen-lockfile
cp .env.example .env.local   &lt;span class="c"&gt;# DATABASE_URL, owner login, provider keys&lt;/span&gt;
pnpm run aurora:migrate      &lt;span class="c"&gt;# applies the schema, idempotent&lt;/span&gt;
pnpm dev                     &lt;span class="c"&gt;# or use the one-click Vercel deploy button&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For production, BabyChain is designed around AWS Aurora. For local development, it can also point at a local PostgreSQL database. The README walks through creating the Aurora cluster, setting &lt;code&gt;DATABASE_URL&lt;/code&gt;, applying the schema, and deploying the app on Vercel.&lt;/p&gt;

&lt;p&gt;The rest of this post is the architecture: how a canvas workflow becomes durable infrastructure on Aurora and Vercel.&lt;/p&gt;

&lt;h2&gt;
  
  
  The architecture: Aurora remembers, Vercel advances
&lt;/h2&gt;

&lt;p&gt;The naive way to run a multi-model chain on serverless is to hold the whole chain in one function invocation. That dies quickly. A single image → video → video-modify workflow can spend several minutes inside provider queues, and a stateless function should not be asked to babysit that entire wait.&lt;/p&gt;

&lt;p&gt;The durable way is to make the database the only place workflow state lives:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Aurora owns every fact about a run.
Vercel functions are stateless workers.
Each invocation advances a run by at most one step.
Any instance can pick up any run mid-chain.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;When a caller creates a run, BabyChain persists the run and its ordered steps to Aurora, may opportunistically advance the first ready step, and returns without waiting for the full chain. Each subsequent poll of &lt;code&gt;GET /api/v1/chains/get/{runId}&lt;/code&gt;, or a cron sweep, loads the run from Aurora, advances exactly one provider step (submit or poll), persists the result, and returns. Long chains survive serverless limits because &lt;strong&gt;no instance ever needs to outlive a step&lt;/strong&gt;.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Aurora owns every fact about a run, so a Vercel function is allowed to disappear at any moment. The chain is not.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Aurora Serverless v2 fits the workload: bursty, low-idle, spiky on demo days. The connection pool absorbs Aurora wake-ups when a cluster is configured to pause with a 30-second connection timeout. For Aurora/RDS endpoints, deployers keep &lt;code&gt;?sslmode=require&lt;/code&gt; in &lt;code&gt;DATABASE_URL&lt;/code&gt;; BabyChain strips the driver-level query param and connects with TLS, including the RDS CA behavior expected by the Node.js &lt;code&gt;pg&lt;/code&gt; client.&lt;/p&gt;

&lt;h2&gt;
  
  
  The schema: seven tables, one source of truth
&lt;/h2&gt;

&lt;p&gt;Everything durable lives in one private schema, &lt;code&gt;babychain_private&lt;/code&gt;, applied idempotently by &lt;code&gt;pnpm aurora:migrate&lt;/code&gt;:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Table&lt;/th&gt;
&lt;th&gt;Owns&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;chain_run&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Run lifecycle: status, input, output, error code/message, idempotency key hash, callback intent&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;chain_step&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Ordered steps: per-step params, provider request ids, generation ids, output files, failure details&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;canvas&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Saved node graphs as &lt;code&gt;jsonb&lt;/code&gt;, owner-scoped, with a touch trigger and a &lt;code&gt;(owner_email, updated_at desc)&lt;/code&gt; index&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;api_key&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Hashed caller keys with scopes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;audit_event&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Append-only audit trail&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;callback_delivery&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Final signed-webhook delivery state&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;babysea_webhook_delivery&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Inbound provider webhook bookkeeping&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Two design details earned their keep:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The &lt;code&gt;input_order&lt;/code&gt; sidecar.&lt;/strong&gt; PostgreSQL &lt;code&gt;jsonb&lt;/code&gt; does not preserve key order, but the public run resource echoes the caller's input back in API responses, and key order is part of how people read their own request. Run creation stores a small &lt;code&gt;jsonb&lt;/code&gt; array of the caller's original key order alongside the canonicalized input, and the presenter re-applies it on the way out. It is a small detail, but it matters when an API response is also a debugging surface.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Guarded state transitions.&lt;/strong&gt; Steps only leave the &lt;code&gt;queued&lt;/code&gt; state through updates with a &lt;code&gt;where status = 'queued'&lt;/code&gt; guard. That single predicate makes the fail-fast path race-safe: when a step fails, the runner marks the run failed and sweeps every still-queued downstream step to &lt;code&gt;skipped&lt;/code&gt; (their input can never arrive) without ever clobbering a step that a concurrent invocation already started.&lt;/p&gt;

&lt;h2&gt;
  
  
  Idempotency end to end
&lt;/h2&gt;

&lt;p&gt;Generative media is expensive enough that retries must not multiply spend. BabyChain makes idempotency a property of the whole pipeline, not one endpoint:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Run creation&lt;/strong&gt; hashes the caller's &lt;code&gt;Idempotency-Key&lt;/code&gt; per principal and stores it on &lt;code&gt;chain_run&lt;/code&gt; with a unique constraint. A retried create replays the stored run: same id, same response, zero new provider calls.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Step submission&lt;/strong&gt; derives a deterministic idempotency key per run, step, and chain version. If a function instance dies between submitting to a provider and persisting the result, the retry resubmits with the same key, and providers that honor idempotency can deduplicate server-side.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The same discipline applies on the way out: when a run includes a webhook URL, the terminal callback is claimed on the run row and each signed delivery attempt is recorded in &lt;code&gt;callback_delivery&lt;/code&gt;, so concurrent instances do not both send the same terminal callback.&lt;/p&gt;

&lt;h2&gt;
  
  
  A canvas that cannot lose your work
&lt;/h2&gt;

&lt;p&gt;The studio is a multi-flow &lt;a href="https://reactflow.dev" rel="noopener noreferrer"&gt;React Flow&lt;/a&gt; canvas. Every edit autosaves to the &lt;code&gt;canvas&lt;/code&gt; table in Aurora, and surviving real-world usage took three iterations:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Debounced autosave is a data-loss bug with good intentions: it can drop the last burst of edits before a reload.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;ul&gt;
&lt;li&gt;A debounce-based autosave silently dropped the last burst of edits before a reload. We replaced it with a &lt;strong&gt;dirty flag plus a steady flush loop&lt;/strong&gt;, so a flush is always at most ~1.5 seconds behind your latest keystroke.&lt;/li&gt;
&lt;li&gt;A &lt;strong&gt;&lt;code&gt;sendBeacon&lt;/code&gt; final flush&lt;/strong&gt; covers tab close, reload, navigation, and tab-hide through an owner-authenticated endpoint.&lt;/li&gt;
&lt;li&gt;Hydration runs exactly once per mount, so router refreshes can never reset live canvas state.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The result is the demo I like most: edit a prompt, log out, log back in on another machine. The edit is there, served from Aurora. Close the tab mid-run, reopen, and the run resumes, because run progress was never in the browser to begin with.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where the real pain lived: provider normalization
&lt;/h2&gt;

&lt;p&gt;Six providers (Alibaba Cloud, Black Forest Labs, BytePlus, Google, OpenAI, and Runway), 57 supported models, 78,948 valid chain combinations. Not one provider agrees on what "give me a 16:9 image" means.&lt;/p&gt;

&lt;p&gt;The deepest rabbit hole was Alibaba Cloud output sizes. Each model family has different rules, documented nowhere and discovered only by probing the live API:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;qwen-image&lt;/code&gt; / &lt;code&gt;qwen-image-plus&lt;/code&gt; accept &lt;strong&gt;exactly five sizes&lt;/strong&gt;. Anything else is a 400.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;qwen-image-max&lt;/code&gt; and &lt;code&gt;z-image-turbo&lt;/code&gt; cap each dimension at 2048.&lt;/li&gt;
&lt;li&gt;The &lt;code&gt;wan2.6&lt;/code&gt; / &lt;code&gt;wan2.7&lt;/code&gt; families enforce per-model &lt;strong&gt;pixel budgets&lt;/strong&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;blockquote&gt;
&lt;p&gt;Provider docs are a starting point. The live API is the truth.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;So the adapter computes sizes per model. For budgeted models, a requested ratio &lt;code&gt;w:h&lt;/code&gt; is fitted into a pixel budget &lt;code&gt;P_max&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;scale = sqrt(P_max / (w * h))
W = floor(scale * w / 16) * 16
H = floor(scale * h / 16) * 16
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;…and snapped-size models get a lookup table instead, because they allow no freedom at all. Wrong sizes now physically cannot be sent.&lt;/p&gt;

&lt;p&gt;The same empirical attitude shaped everything at the boundary: Runway's per-endpoint pixel ratios, OpenAI's permanent quota 429s masquerading as transient rate limits, and BFL output URLs that expire after ~10 minutes (the UI shows honest loading and expiry states instead of leaking alt text).&lt;/p&gt;

&lt;p&gt;One structural decision keeps this manageable: the canvas node cards are &lt;strong&gt;generated from Semantic Lady schemas&lt;/strong&gt; (fields, enum options, ranges, defaults). BabySea mode can lean on BabySea's normalized contract; BYOK mode gets a local provider-aware schema catalog instead of a pile of hand-built forms. The UI cannot offer a parameter the API would reject, because both are projections of the same source of truth.&lt;/p&gt;

&lt;h2&gt;
  
  
  What keeps it honest
&lt;/h2&gt;

&lt;p&gt;BabyChain is built around runtime invariants instead of optimistic workflows. A chain should be able to fail cleanly, resume after an interrupted function, reject invalid model roles and normalized inputs before dispatch, and preserve canvas state even if the browser disappears mid-edit.&lt;/p&gt;

&lt;p&gt;The runtime behavior we validated end to end:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Step fails             -&amp;gt; run goes terminal, downstream steps skipped, caller sees the provider's real error
Function instance dies -&amp;gt; next poll resumes the run from Aurora, idempotent resubmit
Client retries create  -&amp;gt; same run replayed, zero duplicate spend
Tab closes mid-edit    -&amp;gt; sendBeacon flush, canvas intact after re-login
Aurora wake-up         -&amp;gt; 30s connection budget absorbs it when pause is enabled
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The current project gate is 237 tests plus typecheck, lint, and production build. The tests cover the runner, provider adapters, templates, API behavior, migrations, idempotency errors, callback behavior, and the schema rules that keep the canvas and API aligned.&lt;/p&gt;

&lt;h2&gt;
  
  
  What I would do next
&lt;/h2&gt;

&lt;p&gt;BabyChain is already usable as a deployable starter, but the next layer is about making runs cheaper to inspect, easier to share, and safer to operate for teams:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Output archival.&lt;/strong&gt; Copy provider outputs to S3 before short-lived URLs expire, especially for providers whose generated URLs are only useful for minutes.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Branching chains.&lt;/strong&gt; The canvas already runs flows side by side; the runner should support fan-out inside one chain, such as one image feeding multiple video treatments.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Team workspaces.&lt;/strong&gt; Add multi-user accounts with per-key scopes and quotas on top of the existing &lt;code&gt;api_key&lt;/code&gt; model.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Run economics.&lt;/strong&gt; Surface per-run cost estimates and provider spend from the data Aurora already stores.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  The takeaway
&lt;/h2&gt;

&lt;p&gt;Statelessness is a feature you design for, not a constraint you fight. Once every fact about a run lives in Aurora (runs, steps, provider ids, outputs, failures, callbacks, canvases, audit), serverless time limits, cold starts, and instance churn stop being the center of the system. Vercel gives the control plane instant deployment; Aurora gives it durable memory.&lt;/p&gt;

&lt;p&gt;Design on the canvas. Ship the same contract as an API. Let the database remember everything.&lt;/p&gt;

&lt;p&gt;Creators and developers: deploy it, chain your own models in your own cloud, and tell us what you automate first.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Try it: &lt;a href="https://babychain.babysea.live" rel="noopener noreferrer"&gt;https://babychain.babysea.live&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Deploy it: &lt;a href="https://github.com/babysea-community/babychain" rel="noopener noreferrer"&gt;https://github.com/babysea-community/babychain&lt;/a&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Hackathon note
&lt;/h2&gt;

&lt;p&gt;BabyChain is our entry to the &lt;strong&gt;H0: Hack the Zero Stack with Vercel v0 &amp;amp; AWS Databases&lt;/strong&gt; hackathon. This post was created for the purposes of entering that hackathon. #H0Hackathon&lt;/p&gt;

</description>
      <category>ai</category>
      <category>programming</category>
      <category>productivity</category>
      <category>opensource</category>
    </item>
  </channel>
</rss>
