feat(monetize): replace pause annotation with ERC-8004-friendly drain by bussyjd · Pull Request #535 · ObolNetwork/obol-stack

bussyjd · 2026-05-24T08:49:43Z

Problem

Two things were broken about the legacy "pause" path:

Pause was a route on/off switch masquerading as "pause your business."
obol.org/paused: "true" made the controller delete the HTTPRoute
immediately. From a remote x402 buyer's perspective that's
indistinguishable from a crash — and ERC-8004 reputation scorers
that watch a seller's /.well-known/agent-registration.json see an
abrupt disappearance with no advertised wind-down.
obol sell stop was broken. It patched status.conditions[Ready]=False,
which the controller overwrote on the next reconcile. The CLI looked
like it worked; in practice the offer stayed live.

Design

Replace pause with a real drain:

New spec fields advertise the wind-down via discovery before the
route disappears, so external observers can react gracefully.
The HTTPRoute + payment gate stay up during the grace window so
buyers can complete in-flight payments.
After the grace period expires, the controller tears down the route
and marks Draining=False reason=Drained. The CR stays — obol sell delete is still the canonical removal command.

Pure-additive wire shape

Drain is purely additive in the catalog. Active offers serialize
identically to pre-drain releases: no new fields, no shape change. The
only new wire surface is drainEndsAt, which is set on draining offers
only. Consumers detect drain with:

if(entry.drainEndsAt){/* draining; migrate before this time */}

There is no available field. Presence of drainEndsAt is the signal.
This was an explicit design review outcome (commit dd89750): a
separate boolean was redundant and would have been a schema-breaking
change for strict consumers. Now there is zero schema breakage.

API

ServiceOfferSpec:

Field	Type	Default	Behavior
`drainAt`	`*metav1.Time`	nil	When set, offer is draining.
`drainGracePeriod`	`*metav1.Duration`	`1h`	How long after `drainAt` the route stays up. `0s` tears down on the next reconcile.

ServiceOffer helpers: IsDraining(), DrainEndsAt() time.Time,
DrainExpired(now time.Time) bool.

CLI:

obol sell stop <name> -n <ns> # default: drainAt=now, 1h grace
obol sell stop <name> -n <ns> --grace 30m # custom grace
obol sell stop <name> -n <ns> --force # alias: --now; zero grace, abrupt teardown

Discovery surfaces:

/api/services.json: draining entries gain a single drainEndsAt: <RFC3339>
key. Active entries serialize unchanged.
/skill.md: per-service detail block adds a - **Drain ends at**:
bullet only for draining offers. The table gains a Status column
(active: —, draining: draining · ends <RFC3339>).

Drain lifecycle

sequenceDiagram
autonumber
participant Op as Operator
participant CR as ServiceOffer CR
participant Ctl as serviceoffer-controller
participant Disc as /skill.md +<br/>/.well-known/agent-registration.json
participant Route as HTTPRoute + x402 Middleware
participant Buyer as Remote buyer
Op->>CR: obol sell stop my-svc<br/>(patch spec.drainAt=now,<br/>drainGracePeriod=1h)
CR-->>Ctl: Update event
Ctl->>Ctl: IsDraining=true,<br/>DrainExpired=false
Ctl->>Disc: emit drainEndsAt=T+1h<br/>(no `available` field)
Ctl->>Route: KEEP UP
Ctl->>CR: Draining=True reason=Draining
Ctl->>Ctl: AddAfter(T+1h)
Buyer->>Disc: poll catalog
Disc-->>Buyer: drainEndsAt set → migrate
Buyer->>Route: in-flight paid request
Route-->>Buyer: 200 OK
Note over Ctl: ...grace period elapses...
Ctl->>Ctl: DrainExpired=true
Ctl->>Route: deleteRouteChildren()
Ctl->>CR: Draining=False reason=Drained,<br/>PaymentGateReady=False,<br/>RoutePublished=False
Op->>CR: obol sell delete (later, canonical removal)

Why ERC-8004 reputation matters

ERC-8004 makes seller reputation an on-chain signal that buyers and
discovery agents can score. An abrupt route teardown looks identical to
a process crash or upstream outage — a negative reputation event.
Advertising a planned wind-down (drainEndsAt) lets buyers and scorers
distinguish "this seller is gracefully retiring this offer" from
"this seller's infrastructure is unreliable." Even short grace windows
(a few minutes) move the signal from "outage" to "planned maintenance."

Migration

If you were setting obol.org/paused: "true" directly, the annotation
no longer has any effect. To match the old abrupt-teardown semantics:

obol sell stop <name> -n <ns> --force

For the recommended graceful behavior, drop --force and let buyers
see the wind-down via discovery.

Test plan

The legacy obol.org/paused annotation tore down HTTPRoutes immediately, which is indistinguishable from a crash to remote x402 buyers and ERC-8004 reputation scorers. obol sell stop was also broken: it patched status.conditions which the controller immediately overwrote. This replaces both with a real drain: - New ServiceOffer spec.drainAt (date-time) + spec.drainGracePeriod (duration; default 1h) mark an offer as winding down. - While draining, /skill.md and /.well-known/agent-registration.json advertise the offer with available=false and drainEndsAt set, so external discovery can react before traffic disappears. - The HTTPRoute + payment gate stay up until DrainEndsAt, letting in-flight buyers complete payments. - After the grace period, the controller tears down the route, sets Draining=False reason=Drained, and leaves the CR (delete is the canonical removal command). obol sell stop sets spec.drainAt, supports --grace <duration> and --force/--now (zero grace = abrupt teardown for behavior parity with the old annotation).

…e drain signal Design review concluded the `available` boolean was redundant — the presence of `drainEndsAt` is sufficient to signal drain state. This makes the drain wire shape purely additive: active offers serialize identically to pre-drain releases. Wire changes: - ServiceCatalogEntry.Available field removed. - DrainEndsAt is the only drain signal. Consumers detect drain with `if (entry.drainEndsAt) { /* draining */ }`. - /skill.md detail block: no Available bullet on active offers; only draining offers get a "Drain ends at" bullet. - /skill.md table column renamed Available → Status; active rows show "—", draining rows show "draining · ends <RFC3339>". JSON Schema: `available` removed from required and from properties; `drainEndsAt` description updated to "Presence = draining." Tests updated to assert active entries carry NO `available` or `drainEndsAt` keys in the raw JSON, and the markdown detail block for active offers contains no Available line.

bussyjd · 2026-05-24T09:14:14Z

Superseded by bundle PR #536 — closing in favor of the consolidated merge target. Original branch and history preserved.

feat: x402 marketplace + architecture review bundle (#513-#535)

…e drain signal (re-amend of #535) drain becomes purely additive — active offers serialize identically to pre-drain main. The only new wire field is `drainEndsAt`, set on draining offers only. Consumers detect drain with `if (entry.drainEndsAt) { /* draining */ }`. No schema-breaking change for any consumer that was reading the catalog before drain landed. This re-ships an amendment that was originally pushed as commit dd89750 on `feat/drain-replaces-pause` for PR #535. The amendment didn't survive the bundle PR #536's merge into main, so the controller is shipping the un-amended `Available bool` shape today. - ServiceCatalogEntry: remove `Available bool`; keep `DrainEndsAt string omitempty` - service-catalog.schema.json: drop `available` from `required` + `properties` - buildServiceCatalogJSON: stop setting Available; only set DrainEndsAt on drain - buildSkillCatalogMarkdown: rename `Available` table column to `Status` (active rows show `—`; draining rows show `draining · ends <RFC3339>`). Drop the per-service `- **Available**:` bullet entirely; draining services keep only the `- **Drain ends at**:` bullet. - serviceDefWithDrain: stop setting the (already-additive) `Available *bool` on erc8004.ServiceDef during drain; signal via DrainEndsAt only. - Tests: - TestBuildServiceCatalogJSON_ExcludesNonReady: replace `services[0].Available == true` with raw-JSON map walk asserting `available` and `drainEndsAt` keys are absent on active entries. - TestBuildServiceCatalogJSON_DrainLifecycle: rewrite to raw-map walk; assert active entries have neither `available` nor `drainEndsAt`, mid-drain entries have only `drainEndsAt` (no `available`). - TestBuildRegistration{,Identity}Services_IncludesDrainMetadata: replace `svc.Available == &false` checks with `svc.Available == nil` (DrainEndsAt is now the sole drain marker). - Add TestBuildSkillCatalogMarkdown_DrainAdditiveDetail: asserts no `- **Available**:` bullet appears for any offer, that draining offers keep their `- **Drain ends at**:` bullet, and that the table header uses `Status` not `Available`.

bussyjd · 2026-05-24T08:49:43Z

Problem

Two things were broken about the legacy "pause" path:

Pause was a route on/off switch masquerading as "pause your business."
obol.org/paused: "true" made the controller delete the HTTPRoute
immediately. From a remote x402 buyer's perspective that's
indistinguishable from a crash — and ERC-8004 reputation scorers
that watch a seller's /.well-known/agent-registration.json see an
abrupt disappearance with no advertised wind-down.
obol sell stop was broken. It patched status.conditions[Ready]=False,
which the controller overwrote on the next reconcile. The CLI looked
like it worked; in practice the offer stayed live.

Design

Replace pause with a real drain:

New spec fields advertise the wind-down via discovery before the
route disappears, so external observers can react gracefully.
The HTTPRoute + payment gate stay up during the grace window so
buyers can complete in-flight payments.
After the grace period expires, the controller tears down the route
and marks Draining=False reason=Drained. The CR stays — obol sell delete is still the canonical removal command.

Pure-additive wire shape

Drain is purely additive in the catalog. Active offers serialize
identically to pre-drain releases: no new fields, no shape change. The
only new wire surface is drainEndsAt, which is set on draining offers
only. Consumers detect drain with:

if(entry.drainEndsAt){/* draining; migrate before this time */}

There is no available field. Presence of drainEndsAt is the signal.
This was an explicit design review outcome (commit dd89750): a
separate boolean was redundant and would have been a schema-breaking
change for strict consumers. Now there is zero schema breakage.

API

ServiceOfferSpec:

Field	Type	Default	Behavior
`drainAt`	`*metav1.Time`	nil	When set, offer is draining.
`drainGracePeriod`	`*metav1.Duration`	`1h`	How long after `drainAt` the route stays up. `0s` tears down on the next reconcile.

ServiceOffer helpers: IsDraining(), DrainEndsAt() time.Time,
DrainExpired(now time.Time) bool.

CLI:

obol sell stop <name> -n <ns> # default: drainAt=now, 1h grace
obol sell stop <name> -n <ns> --grace 30m # custom grace
obol sell stop <name> -n <ns> --force # alias: --now; zero grace, abrupt teardown

Discovery surfaces:

/api/services.json: draining entries gain a single drainEndsAt: <RFC3339>
key. Active entries serialize unchanged.
/skill.md: per-service detail block adds a - **Drain ends at**:
bullet only for draining offers. The table gains a Status column
(active: —, draining: draining · ends <RFC3339>).

Drain lifecycle

sequenceDiagram
autonumber
participant Op as Operator
participant CR as ServiceOffer CR
participant Ctl as serviceoffer-controller
participant Disc as /skill.md +<br/>/.well-known/agent-registration.json
participant Route as HTTPRoute + x402 Middleware
participant Buyer as Remote buyer
Op->>CR: obol sell stop my-svc<br/>(patch spec.drainAt=now,<br/>drainGracePeriod=1h)
CR-->>Ctl: Update event
Ctl->>Ctl: IsDraining=true,<br/>DrainExpired=false
Ctl->>Disc: emit drainEndsAt=T+1h<br/>(no `available` field)
Ctl->>Route: KEEP UP
Ctl->>CR: Draining=True reason=Draining
Ctl->>Ctl: AddAfter(T+1h)
Buyer->>Disc: poll catalog
Disc-->>Buyer: drainEndsAt set → migrate
Buyer->>Route: in-flight paid request
Route-->>Buyer: 200 OK
Note over Ctl: ...grace period elapses...
Ctl->>Ctl: DrainExpired=true
Ctl->>Route: deleteRouteChildren()
Ctl->>CR: Draining=False reason=Drained,<br/>PaymentGateReady=False,<br/>RoutePublished=False
Op->>CR: obol sell delete (later, canonical removal)

Why ERC-8004 reputation matters

ERC-8004 makes seller reputation an on-chain signal that buyers and
discovery agents can score. An abrupt route teardown looks identical to
a process crash or upstream outage — a negative reputation event.
Advertising a planned wind-down (drainEndsAt) lets buyers and scorers
distinguish "this seller is gracefully retiring this offer" from
"this seller's infrastructure is unreliable." Even short grace windows
(a few minutes) move the signal from "outage" to "planned maintenance."

Migration

If you were setting obol.org/paused: "true" directly, the annotation
no longer has any effect. To match the old abrupt-teardown semantics:

obol sell stop <name> -n <ns> --force

For the recommended graceful behavior, drop --force and let buyers
see the wind-down via discovery.

Test plan

The legacy obol.org/paused annotation tore down HTTPRoutes immediately, which is indistinguishable from a crash to remote x402 buyers and ERC-8004 reputation scorers. obol sell stop was also broken: it patched status.conditions which the controller immediately overwrote. This replaces both with a real drain: - New ServiceOffer spec.drainAt (date-time) + spec.drainGracePeriod (duration; default 1h) mark an offer as winding down. - While draining, /skill.md and /.well-known/agent-registration.json advertise the offer with available=false and drainEndsAt set, so external discovery can react before traffic disappears. - The HTTPRoute + payment gate stay up until DrainEndsAt, letting in-flight buyers complete payments. - After the grace period, the controller tears down the route, sets Draining=False reason=Drained, and leaves the CR (delete is the canonical removal command). obol sell stop sets spec.drainAt, supports --grace <duration> and --force/--now (zero grace = abrupt teardown for behavior parity with the old annotation).

…e drain signal Design review concluded the `available` boolean was redundant — the presence of `drainEndsAt` is sufficient to signal drain state. This makes the drain wire shape purely additive: active offers serialize identically to pre-drain releases. Wire changes: - ServiceCatalogEntry.Available field removed. - DrainEndsAt is the only drain signal. Consumers detect drain with `if (entry.drainEndsAt) { /* draining */ }`. - /skill.md detail block: no Available bullet on active offers; only draining offers get a "Drain ends at" bullet. - /skill.md table column renamed Available → Status; active rows show "—", draining rows show "draining · ends <RFC3339>". JSON Schema: `available` removed from required and from properties; `drainEndsAt` description updated to "Presence = draining." Tests updated to assert active entries carry NO `available` or `drainEndsAt` keys in the raw JSON, and the markdown detail block for active offers contains no Available line.

bussyjd · 2026-05-24T09:14:14Z

Superseded by bundle PR #536 — closing in favor of the consolidated merge target. Original branch and history preserved.

feat: x402 marketplace + architecture review bundle (#513-#535)

…e drain signal (re-amend of #535) drain becomes purely additive — active offers serialize identically to pre-drain main. The only new wire field is `drainEndsAt`, set on draining offers only. Consumers detect drain with `if (entry.drainEndsAt) { /* draining */ }`. No schema-breaking change for any consumer that was reading the catalog before drain landed. This re-ships an amendment that was originally pushed as commit dd89750 on `feat/drain-replaces-pause` for PR #535. The amendment didn't survive the bundle PR #536's merge into main, so the controller is shipping the un-amended `Available bool` shape today. - ServiceCatalogEntry: remove `Available bool`; keep `DrainEndsAt string omitempty` - service-catalog.schema.json: drop `available` from `required` + `properties` - buildServiceCatalogJSON: stop setting Available; only set DrainEndsAt on drain - buildSkillCatalogMarkdown: rename `Available` table column to `Status` (active rows show `—`; draining rows show `draining · ends <RFC3339>`). Drop the per-service `- **Available**:` bullet entirely; draining services keep only the `- **Drain ends at**:` bullet. - serviceDefWithDrain: stop setting the (already-additive) `Available *bool` on erc8004.ServiceDef during drain; signal via DrainEndsAt only. - Tests: - TestBuildServiceCatalogJSON_ExcludesNonReady: replace `services[0].Available == true` with raw-JSON map walk asserting `available` and `drainEndsAt` keys are absent on active entries. - TestBuildServiceCatalogJSON_DrainLifecycle: rewrite to raw-map walk; assert active entries have neither `available` nor `drainEndsAt`, mid-drain entries have only `drainEndsAt` (no `available`). - TestBuildRegistration{,Identity}Services_IncludesDrainMetadata: replace `svc.Available == &false` checks with `svc.Available == nil` (DrainEndsAt is now the sole drain marker). - Add TestBuildSkillCatalogMarkdown_DrainAdditiveDetail: asserts no `- **Available**:` bullet appears for any offer, that draining offers keep their `- **Drain ends at**:` bullet, and that the table header uses `Status` not `Available`.

bussyjd · 2026-05-24T08:49:43Z

Problem

Two things were broken about the legacy "pause" path:

Pause was a route on/off switch masquerading as "pause your business."
obol.org/paused: "true" made the controller delete the HTTPRoute
immediately. From a remote x402 buyer's perspective that's
indistinguishable from a crash — and ERC-8004 reputation scorers
that watch a seller's /.well-known/agent-registration.json see an
abrupt disappearance with no advertised wind-down.
obol sell stop was broken. It patched status.conditions[Ready]=False,
which the controller overwrote on the next reconcile. The CLI looked
like it worked; in practice the offer stayed live.

Design

Replace pause with a real drain:

New spec fields advertise the wind-down via discovery before the
route disappears, so external observers can react gracefully.
The HTTPRoute + payment gate stay up during the grace window so
buyers can complete in-flight payments.
After the grace period expires, the controller tears down the route
and marks Draining=False reason=Drained. The CR stays — obol sell delete is still the canonical removal command.

Pure-additive wire shape

Drain is purely additive in the catalog. Active offers serialize
identically to pre-drain releases: no new fields, no shape change. The
only new wire surface is drainEndsAt, which is set on draining offers
only. Consumers detect drain with:

if(entry.drainEndsAt){/* draining; migrate before this time */}

There is no available field. Presence of drainEndsAt is the signal.
This was an explicit design review outcome (commit dd89750): a
separate boolean was redundant and would have been a schema-breaking
change for strict consumers. Now there is zero schema breakage.

API

ServiceOfferSpec:

Field	Type	Default	Behavior
`drainAt`	`*metav1.Time`	nil	When set, offer is draining.
`drainGracePeriod`	`*metav1.Duration`	`1h`	How long after `drainAt` the route stays up. `0s` tears down on the next reconcile.

ServiceOffer helpers: IsDraining(), DrainEndsAt() time.Time,
DrainExpired(now time.Time) bool.

CLI:

obol sell stop <name> -n <ns> # default: drainAt=now, 1h grace
obol sell stop <name> -n <ns> --grace 30m # custom grace
obol sell stop <name> -n <ns> --force # alias: --now; zero grace, abrupt teardown

Discovery surfaces:

/api/services.json: draining entries gain a single drainEndsAt: <RFC3339>
key. Active entries serialize unchanged.
/skill.md: per-service detail block adds a - **Drain ends at**:
bullet only for draining offers. The table gains a Status column
(active: —, draining: draining · ends <RFC3339>).

Drain lifecycle

sequenceDiagram
autonumber
participant Op as Operator
participant CR as ServiceOffer CR
participant Ctl as serviceoffer-controller
participant Disc as /skill.md +<br/>/.well-known/agent-registration.json
participant Route as HTTPRoute + x402 Middleware
participant Buyer as Remote buyer
Op->>CR: obol sell stop my-svc<br/>(patch spec.drainAt=now,<br/>drainGracePeriod=1h)
CR-->>Ctl: Update event
Ctl->>Ctl: IsDraining=true,<br/>DrainExpired=false
Ctl->>Disc: emit drainEndsAt=T+1h<br/>(no `available` field)
Ctl->>Route: KEEP UP
Ctl->>CR: Draining=True reason=Draining
Ctl->>Ctl: AddAfter(T+1h)
Buyer->>Disc: poll catalog
Disc-->>Buyer: drainEndsAt set → migrate
Buyer->>Route: in-flight paid request
Route-->>Buyer: 200 OK
Note over Ctl: ...grace period elapses...
Ctl->>Ctl: DrainExpired=true
Ctl->>Route: deleteRouteChildren()
Ctl->>CR: Draining=False reason=Drained,<br/>PaymentGateReady=False,<br/>RoutePublished=False
Op->>CR: obol sell delete (later, canonical removal)

Why ERC-8004 reputation matters

ERC-8004 makes seller reputation an on-chain signal that buyers and
discovery agents can score. An abrupt route teardown looks identical to
a process crash or upstream outage — a negative reputation event.
Advertising a planned wind-down (drainEndsAt) lets buyers and scorers
distinguish "this seller is gracefully retiring this offer" from
"this seller's infrastructure is unreliable." Even short grace windows
(a few minutes) move the signal from "outage" to "planned maintenance."

Migration

If you were setting obol.org/paused: "true" directly, the annotation
no longer has any effect. To match the old abrupt-teardown semantics:

obol sell stop <name> -n <ns> --force

For the recommended graceful behavior, drop --force and let buyers
see the wind-down via discovery.

Test plan

The legacy obol.org/paused annotation tore down HTTPRoutes immediately, which is indistinguishable from a crash to remote x402 buyers and ERC-8004 reputation scorers. obol sell stop was also broken: it patched status.conditions which the controller immediately overwrote. This replaces both with a real drain: - New ServiceOffer spec.drainAt (date-time) + spec.drainGracePeriod (duration; default 1h) mark an offer as winding down. - While draining, /skill.md and /.well-known/agent-registration.json advertise the offer with available=false and drainEndsAt set, so external discovery can react before traffic disappears. - The HTTPRoute + payment gate stay up until DrainEndsAt, letting in-flight buyers complete payments. - After the grace period, the controller tears down the route, sets Draining=False reason=Drained, and leaves the CR (delete is the canonical removal command). obol sell stop sets spec.drainAt, supports --grace <duration> and --force/--now (zero grace = abrupt teardown for behavior parity with the old annotation).

…e drain signal Design review concluded the `available` boolean was redundant — the presence of `drainEndsAt` is sufficient to signal drain state. This makes the drain wire shape purely additive: active offers serialize identically to pre-drain releases. Wire changes: - ServiceCatalogEntry.Available field removed. - DrainEndsAt is the only drain signal. Consumers detect drain with `if (entry.drainEndsAt) { /* draining */ }`. - /skill.md detail block: no Available bullet on active offers; only draining offers get a "Drain ends at" bullet. - /skill.md table column renamed Available → Status; active rows show "—", draining rows show "draining · ends <RFC3339>". JSON Schema: `available` removed from required and from properties; `drainEndsAt` description updated to "Presence = draining." Tests updated to assert active entries carry NO `available` or `drainEndsAt` keys in the raw JSON, and the markdown detail block for active offers contains no Available line.

bussyjd · 2026-05-24T09:14:14Z

Superseded by bundle PR #536 — closing in favor of the consolidated merge target. Original branch and history preserved.

feat: x402 marketplace + architecture review bundle (#513-#535)

…e drain signal (re-amend of #535) drain becomes purely additive — active offers serialize identically to pre-drain main. The only new wire field is `drainEndsAt`, set on draining offers only. Consumers detect drain with `if (entry.drainEndsAt) { /* draining */ }`. No schema-breaking change for any consumer that was reading the catalog before drain landed. This re-ships an amendment that was originally pushed as commit dd89750 on `feat/drain-replaces-pause` for PR #535. The amendment didn't survive the bundle PR #536's merge into main, so the controller is shipping the un-amended `Available bool` shape today. - ServiceCatalogEntry: remove `Available bool`; keep `DrainEndsAt string omitempty` - service-catalog.schema.json: drop `available` from `required` + `properties` - buildServiceCatalogJSON: stop setting Available; only set DrainEndsAt on drain - buildSkillCatalogMarkdown: rename `Available` table column to `Status` (active rows show `—`; draining rows show `draining · ends <RFC3339>`). Drop the per-service `- **Available**:` bullet entirely; draining services keep only the `- **Drain ends at**:` bullet. - serviceDefWithDrain: stop setting the (already-additive) `Available *bool` on erc8004.ServiceDef during drain; signal via DrainEndsAt only. - Tests: - TestBuildServiceCatalogJSON_ExcludesNonReady: replace `services[0].Available == true` with raw-JSON map walk asserting `available` and `drainEndsAt` keys are absent on active entries. - TestBuildServiceCatalogJSON_DrainLifecycle: rewrite to raw-map walk; assert active entries have neither `available` nor `drainEndsAt`, mid-drain entries have only `drainEndsAt` (no `available`). - TestBuildRegistration{,Identity}Services_IncludesDrainMetadata: replace `svc.Available == &false` checks with `svc.Available == nil` (DrainEndsAt is now the sole drain marker). - Add TestBuildSkillCatalogMarkdown_DrainAdditiveDetail: asserts no `- **Available**:` bullet appears for any offer, that draining offers keep their `- **Drain ends at**:` bullet, and that the table header uses `Status` not `Available`.

bussyjd · 2026-05-24T08:49:43Z

Problem

Two things were broken about the legacy "pause" path:

Pause was a route on/off switch masquerading as "pause your business."
obol.org/paused: "true" made the controller delete the HTTPRoute
immediately. From a remote x402 buyer's perspective that's
indistinguishable from a crash — and ERC-8004 reputation scorers
that watch a seller's /.well-known/agent-registration.json see an
abrupt disappearance with no advertised wind-down.
obol sell stop was broken. It patched status.conditions[Ready]=False,
which the controller overwrote on the next reconcile. The CLI looked
like it worked; in practice the offer stayed live.

Design

Replace pause with a real drain:

New spec fields advertise the wind-down via discovery before the
route disappears, so external observers can react gracefully.
The HTTPRoute + payment gate stay up during the grace window so
buyers can complete in-flight payments.
After the grace period expires, the controller tears down the route
and marks Draining=False reason=Drained. The CR stays — obol sell delete is still the canonical removal command.

Pure-additive wire shape

Drain is purely additive in the catalog. Active offers serialize
identically to pre-drain releases: no new fields, no shape change. The
only new wire surface is drainEndsAt, which is set on draining offers
only. Consumers detect drain with:

if(entry.drainEndsAt){/* draining; migrate before this time */}

There is no available field. Presence of drainEndsAt is the signal.
This was an explicit design review outcome (commit dd89750): a
separate boolean was redundant and would have been a schema-breaking
change for strict consumers. Now there is zero schema breakage.

API

ServiceOfferSpec:

Field	Type	Default	Behavior
`drainAt`	`*metav1.Time`	nil	When set, offer is draining.
`drainGracePeriod`	`*metav1.Duration`	`1h`	How long after `drainAt` the route stays up. `0s` tears down on the next reconcile.

ServiceOffer helpers: IsDraining(), DrainEndsAt() time.Time,
DrainExpired(now time.Time) bool.

CLI:

obol sell stop <name> -n <ns> # default: drainAt=now, 1h grace
obol sell stop <name> -n <ns> --grace 30m # custom grace
obol sell stop <name> -n <ns> --force # alias: --now; zero grace, abrupt teardown

Discovery surfaces:

/api/services.json: draining entries gain a single drainEndsAt: <RFC3339>
key. Active entries serialize unchanged.
/skill.md: per-service detail block adds a - **Drain ends at**:
bullet only for draining offers. The table gains a Status column
(active: —, draining: draining · ends <RFC3339>).

Drain lifecycle

sequenceDiagram
autonumber
participant Op as Operator
participant CR as ServiceOffer CR
participant Ctl as serviceoffer-controller
participant Disc as /skill.md +<br/>/.well-known/agent-registration.json
participant Route as HTTPRoute + x402 Middleware
participant Buyer as Remote buyer
Op->>CR: obol sell stop my-svc<br/>(patch spec.drainAt=now,<br/>drainGracePeriod=1h)
CR-->>Ctl: Update event
Ctl->>Ctl: IsDraining=true,<br/>DrainExpired=false
Ctl->>Disc: emit drainEndsAt=T+1h<br/>(no `available` field)
Ctl->>Route: KEEP UP
Ctl->>CR: Draining=True reason=Draining
Ctl->>Ctl: AddAfter(T+1h)
Buyer->>Disc: poll catalog
Disc-->>Buyer: drainEndsAt set → migrate
Buyer->>Route: in-flight paid request
Route-->>Buyer: 200 OK
Note over Ctl: ...grace period elapses...
Ctl->>Ctl: DrainExpired=true
Ctl->>Route: deleteRouteChildren()
Ctl->>CR: Draining=False reason=Drained,<br/>PaymentGateReady=False,<br/>RoutePublished=False
Op->>CR: obol sell delete (later, canonical removal)

Why ERC-8004 reputation matters

ERC-8004 makes seller reputation an on-chain signal that buyers and
discovery agents can score. An abrupt route teardown looks identical to
a process crash or upstream outage — a negative reputation event.
Advertising a planned wind-down (drainEndsAt) lets buyers and scorers
distinguish "this seller is gracefully retiring this offer" from
"this seller's infrastructure is unreliable." Even short grace windows
(a few minutes) move the signal from "outage" to "planned maintenance."

Migration

If you were setting obol.org/paused: "true" directly, the annotation
no longer has any effect. To match the old abrupt-teardown semantics:

obol sell stop <name> -n <ns> --force

For the recommended graceful behavior, drop --force and let buyers
see the wind-down via discovery.

Test plan

The legacy obol.org/paused annotation tore down HTTPRoutes immediately, which is indistinguishable from a crash to remote x402 buyers and ERC-8004 reputation scorers. obol sell stop was also broken: it patched status.conditions which the controller immediately overwrote. This replaces both with a real drain: - New ServiceOffer spec.drainAt (date-time) + spec.drainGracePeriod (duration; default 1h) mark an offer as winding down. - While draining, /skill.md and /.well-known/agent-registration.json advertise the offer with available=false and drainEndsAt set, so external discovery can react before traffic disappears. - The HTTPRoute + payment gate stay up until DrainEndsAt, letting in-flight buyers complete payments. - After the grace period, the controller tears down the route, sets Draining=False reason=Drained, and leaves the CR (delete is the canonical removal command). obol sell stop sets spec.drainAt, supports --grace <duration> and --force/--now (zero grace = abrupt teardown for behavior parity with the old annotation).

…e drain signal Design review concluded the `available` boolean was redundant — the presence of `drainEndsAt` is sufficient to signal drain state. This makes the drain wire shape purely additive: active offers serialize identically to pre-drain releases. Wire changes: - ServiceCatalogEntry.Available field removed. - DrainEndsAt is the only drain signal. Consumers detect drain with `if (entry.drainEndsAt) { /* draining */ }`. - /skill.md detail block: no Available bullet on active offers; only draining offers get a "Drain ends at" bullet. - /skill.md table column renamed Available → Status; active rows show "—", draining rows show "draining · ends <RFC3339>". JSON Schema: `available` removed from required and from properties; `drainEndsAt` description updated to "Presence = draining." Tests updated to assert active entries carry NO `available` or `drainEndsAt` keys in the raw JSON, and the markdown detail block for active offers contains no Available line.

bussyjd · 2026-05-24T09:14:14Z

Superseded by bundle PR #536 — closing in favor of the consolidated merge target. Original branch and history preserved.

feat: x402 marketplace + architecture review bundle (#513-#535)

…e drain signal (re-amend of #535) drain becomes purely additive — active offers serialize identically to pre-drain main. The only new wire field is `drainEndsAt`, set on draining offers only. Consumers detect drain with `if (entry.drainEndsAt) { /* draining */ }`. No schema-breaking change for any consumer that was reading the catalog before drain landed. This re-ships an amendment that was originally pushed as commit dd89750 on `feat/drain-replaces-pause` for PR #535. The amendment didn't survive the bundle PR #536's merge into main, so the controller is shipping the un-amended `Available bool` shape today. - ServiceCatalogEntry: remove `Available bool`; keep `DrainEndsAt string omitempty` - service-catalog.schema.json: drop `available` from `required` + `properties` - buildServiceCatalogJSON: stop setting Available; only set DrainEndsAt on drain - buildSkillCatalogMarkdown: rename `Available` table column to `Status` (active rows show `—`; draining rows show `draining · ends <RFC3339>`). Drop the per-service `- **Available**:` bullet entirely; draining services keep only the `- **Drain ends at**:` bullet. - serviceDefWithDrain: stop setting the (already-additive) `Available *bool` on erc8004.ServiceDef during drain; signal via DrainEndsAt only. - Tests: - TestBuildServiceCatalogJSON_ExcludesNonReady: replace `services[0].Available == true` with raw-JSON map walk asserting `available` and `drainEndsAt` keys are absent on active entries. - TestBuildServiceCatalogJSON_DrainLifecycle: rewrite to raw-map walk; assert active entries have neither `available` nor `drainEndsAt`, mid-drain entries have only `drainEndsAt` (no `available`). - TestBuildRegistration{,Identity}Services_IncludesDrainMetadata: replace `svc.Available == &false` checks with `svc.Available == nil` (DrainEndsAt is now the sole drain marker). - Add TestBuildSkillCatalogMarkdown_DrainAdditiveDetail: asserts no `- **Available**:` bullet appears for any offer, that draining offers keep their `- **Drain ends at**:` bullet, and that the table header uses `Status` not `Available`.

bussyjd · 2026-05-24T08:49:43Z

Problem

Two things were broken about the legacy "pause" path:

Pause was a route on/off switch masquerading as "pause your business."
obol.org/paused: "true" made the controller delete the HTTPRoute
immediately. From a remote x402 buyer's perspective that's
indistinguishable from a crash — and ERC-8004 reputation scorers
that watch a seller's /.well-known/agent-registration.json see an
abrupt disappearance with no advertised wind-down.
obol sell stop was broken. It patched status.conditions[Ready]=False,
which the controller overwrote on the next reconcile. The CLI looked
like it worked; in practice the offer stayed live.

Design

Replace pause with a real drain:

New spec fields advertise the wind-down via discovery before the
route disappears, so external observers can react gracefully.
The HTTPRoute + payment gate stay up during the grace window so
buyers can complete in-flight payments.
After the grace period expires, the controller tears down the route
and marks Draining=False reason=Drained. The CR stays — obol sell delete is still the canonical removal command.

Pure-additive wire shape

Drain is purely additive in the catalog. Active offers serialize
identically to pre-drain releases: no new fields, no shape change. The
only new wire surface is drainEndsAt, which is set on draining offers
only. Consumers detect drain with:

if(entry.drainEndsAt){/* draining; migrate before this time */}

There is no available field. Presence of drainEndsAt is the signal.
This was an explicit design review outcome (commit dd89750): a
separate boolean was redundant and would have been a schema-breaking
change for strict consumers. Now there is zero schema breakage.

API

ServiceOfferSpec:

Field	Type	Default	Behavior
`drainAt`	`*metav1.Time`	nil	When set, offer is draining.
`drainGracePeriod`	`*metav1.Duration`	`1h`	How long after `drainAt` the route stays up. `0s` tears down on the next reconcile.

ServiceOffer helpers: IsDraining(), DrainEndsAt() time.Time,
DrainExpired(now time.Time) bool.

CLI:

obol sell stop <name> -n <ns> # default: drainAt=now, 1h grace
obol sell stop <name> -n <ns> --grace 30m # custom grace
obol sell stop <name> -n <ns> --force # alias: --now; zero grace, abrupt teardown

Discovery surfaces:

/api/services.json: draining entries gain a single drainEndsAt: <RFC3339>
key. Active entries serialize unchanged.
/skill.md: per-service detail block adds a - **Drain ends at**:
bullet only for draining offers. The table gains a Status column
(active: —, draining: draining · ends <RFC3339>).

Drain lifecycle

sequenceDiagram
autonumber
participant Op as Operator
participant CR as ServiceOffer CR
participant Ctl as serviceoffer-controller
participant Disc as /skill.md +<br/>/.well-known/agent-registration.json
participant Route as HTTPRoute + x402 Middleware
participant Buyer as Remote buyer
Op->>CR: obol sell stop my-svc<br/>(patch spec.drainAt=now,<br/>drainGracePeriod=1h)
CR-->>Ctl: Update event
Ctl->>Ctl: IsDraining=true,<br/>DrainExpired=false
Ctl->>Disc: emit drainEndsAt=T+1h<br/>(no `available` field)
Ctl->>Route: KEEP UP
Ctl->>CR: Draining=True reason=Draining
Ctl->>Ctl: AddAfter(T+1h)
Buyer->>Disc: poll catalog
Disc-->>Buyer: drainEndsAt set → migrate
Buyer->>Route: in-flight paid request
Route-->>Buyer: 200 OK
Note over Ctl: ...grace period elapses...
Ctl->>Ctl: DrainExpired=true
Ctl->>Route: deleteRouteChildren()
Ctl->>CR: Draining=False reason=Drained,<br/>PaymentGateReady=False,<br/>RoutePublished=False
Op->>CR: obol sell delete (later, canonical removal)

Why ERC-8004 reputation matters

ERC-8004 makes seller reputation an on-chain signal that buyers and
discovery agents can score. An abrupt route teardown looks identical to
a process crash or upstream outage — a negative reputation event.
Advertising a planned wind-down (drainEndsAt) lets buyers and scorers
distinguish "this seller is gracefully retiring this offer" from
"this seller's infrastructure is unreliable." Even short grace windows
(a few minutes) move the signal from "outage" to "planned maintenance."

Migration

If you were setting obol.org/paused: "true" directly, the annotation
no longer has any effect. To match the old abrupt-teardown semantics:

obol sell stop <name> -n <ns> --force

For the recommended graceful behavior, drop --force and let buyers
see the wind-down via discovery.

Test plan

The legacy obol.org/paused annotation tore down HTTPRoutes immediately, which is indistinguishable from a crash to remote x402 buyers and ERC-8004 reputation scorers. obol sell stop was also broken: it patched status.conditions which the controller immediately overwrote. This replaces both with a real drain: - New ServiceOffer spec.drainAt (date-time) + spec.drainGracePeriod (duration; default 1h) mark an offer as winding down. - While draining, /skill.md and /.well-known/agent-registration.json advertise the offer with available=false and drainEndsAt set, so external discovery can react before traffic disappears. - The HTTPRoute + payment gate stay up until DrainEndsAt, letting in-flight buyers complete payments. - After the grace period, the controller tears down the route, sets Draining=False reason=Drained, and leaves the CR (delete is the canonical removal command). obol sell stop sets spec.drainAt, supports --grace <duration> and --force/--now (zero grace = abrupt teardown for behavior parity with the old annotation).

…e drain signal Design review concluded the `available` boolean was redundant — the presence of `drainEndsAt` is sufficient to signal drain state. This makes the drain wire shape purely additive: active offers serialize identically to pre-drain releases. Wire changes: - ServiceCatalogEntry.Available field removed. - DrainEndsAt is the only drain signal. Consumers detect drain with `if (entry.drainEndsAt) { /* draining */ }`. - /skill.md detail block: no Available bullet on active offers; only draining offers get a "Drain ends at" bullet. - /skill.md table column renamed Available → Status; active rows show "—", draining rows show "draining · ends <RFC3339>". JSON Schema: `available` removed from required and from properties; `drainEndsAt` description updated to "Presence = draining." Tests updated to assert active entries carry NO `available` or `drainEndsAt` keys in the raw JSON, and the markdown detail block for active offers contains no Available line.

bussyjd · 2026-05-24T09:14:14Z

Superseded by bundle PR #536 — closing in favor of the consolidated merge target. Original branch and history preserved.

feat: x402 marketplace + architecture review bundle (#513-#535)

…e drain signal (re-amend of #535) drain becomes purely additive — active offers serialize identically to pre-drain main. The only new wire field is `drainEndsAt`, set on draining offers only. Consumers detect drain with `if (entry.drainEndsAt) { /* draining */ }`. No schema-breaking change for any consumer that was reading the catalog before drain landed. This re-ships an amendment that was originally pushed as commit dd89750 on `feat/drain-replaces-pause` for PR #535. The amendment didn't survive the bundle PR #536's merge into main, so the controller is shipping the un-amended `Available bool` shape today. - ServiceCatalogEntry: remove `Available bool`; keep `DrainEndsAt string omitempty` - service-catalog.schema.json: drop `available` from `required` + `properties` - buildServiceCatalogJSON: stop setting Available; only set DrainEndsAt on drain - buildSkillCatalogMarkdown: rename `Available` table column to `Status` (active rows show `—`; draining rows show `draining · ends <RFC3339>`). Drop the per-service `- **Available**:` bullet entirely; draining services keep only the `- **Drain ends at**:` bullet. - serviceDefWithDrain: stop setting the (already-additive) `Available *bool` on erc8004.ServiceDef during drain; signal via DrainEndsAt only. - Tests: - TestBuildServiceCatalogJSON_ExcludesNonReady: replace `services[0].Available == true` with raw-JSON map walk asserting `available` and `drainEndsAt` keys are absent on active entries. - TestBuildServiceCatalogJSON_DrainLifecycle: rewrite to raw-map walk; assert active entries have neither `available` nor `drainEndsAt`, mid-drain entries have only `drainEndsAt` (no `available`). - TestBuildRegistration{,Identity}Services_IncludesDrainMetadata: replace `svc.Available == &false` checks with `svc.Available == nil` (DrainEndsAt is now the sole drain marker). - Add TestBuildSkillCatalogMarkdown_DrainAdditiveDetail: asserts no `- **Available**:` bullet appears for any offer, that draining offers keep their `- **Drain ends at**:` bullet, and that the table header uses `Status` not `Available`.

bussyjd · 2026-05-24T08:49:43Z

Problem

Two things were broken about the legacy "pause" path:

Pause was a route on/off switch masquerading as "pause your business."
obol.org/paused: "true" made the controller delete the HTTPRoute
immediately. From a remote x402 buyer's perspective that's
indistinguishable from a crash — and ERC-8004 reputation scorers
that watch a seller's /.well-known/agent-registration.json see an
abrupt disappearance with no advertised wind-down.
obol sell stop was broken. It patched status.conditions[Ready]=False,
which the controller overwrote on the next reconcile. The CLI looked
like it worked; in practice the offer stayed live.

Design

Replace pause with a real drain:

New spec fields advertise the wind-down via discovery before the
route disappears, so external observers can react gracefully.
The HTTPRoute + payment gate stay up during the grace window so
buyers can complete in-flight payments.
After the grace period expires, the controller tears down the route
and marks Draining=False reason=Drained. The CR stays — obol sell delete is still the canonical removal command.

Pure-additive wire shape

Drain is purely additive in the catalog. Active offers serialize
identically to pre-drain releases: no new fields, no shape change. The
only new wire surface is drainEndsAt, which is set on draining offers
only. Consumers detect drain with:

if(entry.drainEndsAt){/* draining; migrate before this time */}

There is no available field. Presence of drainEndsAt is the signal.
This was an explicit design review outcome (commit dd89750): a
separate boolean was redundant and would have been a schema-breaking
change for strict consumers. Now there is zero schema breakage.

API

ServiceOfferSpec:

Field	Type	Default	Behavior
`drainAt`	`*metav1.Time`	nil	When set, offer is draining.
`drainGracePeriod`	`*metav1.Duration`	`1h`	How long after `drainAt` the route stays up. `0s` tears down on the next reconcile.

ServiceOffer helpers: IsDraining(), DrainEndsAt() time.Time,
DrainExpired(now time.Time) bool.

CLI:

obol sell stop <name> -n <ns> # default: drainAt=now, 1h grace
obol sell stop <name> -n <ns> --grace 30m # custom grace
obol sell stop <name> -n <ns> --force # alias: --now; zero grace, abrupt teardown

Discovery surfaces:

/api/services.json: draining entries gain a single drainEndsAt: <RFC3339>
key. Active entries serialize unchanged.
/skill.md: per-service detail block adds a - **Drain ends at**:
bullet only for draining offers. The table gains a Status column
(active: —, draining: draining · ends <RFC3339>).

Drain lifecycle

sequenceDiagram
autonumber
participant Op as Operator
participant CR as ServiceOffer CR
participant Ctl as serviceoffer-controller
participant Disc as /skill.md +<br/>/.well-known/agent-registration.json
participant Route as HTTPRoute + x402 Middleware
participant Buyer as Remote buyer
Op->>CR: obol sell stop my-svc<br/>(patch spec.drainAt=now,<br/>drainGracePeriod=1h)
CR-->>Ctl: Update event
Ctl->>Ctl: IsDraining=true,<br/>DrainExpired=false
Ctl->>Disc: emit drainEndsAt=T+1h<br/>(no `available` field)
Ctl->>Route: KEEP UP
Ctl->>CR: Draining=True reason=Draining
Ctl->>Ctl: AddAfter(T+1h)
Buyer->>Disc: poll catalog
Disc-->>Buyer: drainEndsAt set → migrate
Buyer->>Route: in-flight paid request
Route-->>Buyer: 200 OK
Note over Ctl: ...grace period elapses...
Ctl->>Ctl: DrainExpired=true
Ctl->>Route: deleteRouteChildren()
Ctl->>CR: Draining=False reason=Drained,<br/>PaymentGateReady=False,<br/>RoutePublished=False
Op->>CR: obol sell delete (later, canonical removal)

Why ERC-8004 reputation matters

ERC-8004 makes seller reputation an on-chain signal that buyers and
discovery agents can score. An abrupt route teardown looks identical to
a process crash or upstream outage — a negative reputation event.
Advertising a planned wind-down (drainEndsAt) lets buyers and scorers
distinguish "this seller is gracefully retiring this offer" from
"this seller's infrastructure is unreliable." Even short grace windows
(a few minutes) move the signal from "outage" to "planned maintenance."

Migration

If you were setting obol.org/paused: "true" directly, the annotation
no longer has any effect. To match the old abrupt-teardown semantics:

obol sell stop <name> -n <ns> --force

For the recommended graceful behavior, drop --force and let buyers
see the wind-down via discovery.

Test plan

The legacy obol.org/paused annotation tore down HTTPRoutes immediately, which is indistinguishable from a crash to remote x402 buyers and ERC-8004 reputation scorers. obol sell stop was also broken: it patched status.conditions which the controller immediately overwrote. This replaces both with a real drain: - New ServiceOffer spec.drainAt (date-time) + spec.drainGracePeriod (duration; default 1h) mark an offer as winding down. - While draining, /skill.md and /.well-known/agent-registration.json advertise the offer with available=false and drainEndsAt set, so external discovery can react before traffic disappears. - The HTTPRoute + payment gate stay up until DrainEndsAt, letting in-flight buyers complete payments. - After the grace period, the controller tears down the route, sets Draining=False reason=Drained, and leaves the CR (delete is the canonical removal command). obol sell stop sets spec.drainAt, supports --grace <duration> and --force/--now (zero grace = abrupt teardown for behavior parity with the old annotation).

…e drain signal Design review concluded the `available` boolean was redundant — the presence of `drainEndsAt` is sufficient to signal drain state. This makes the drain wire shape purely additive: active offers serialize identically to pre-drain releases. Wire changes: - ServiceCatalogEntry.Available field removed. - DrainEndsAt is the only drain signal. Consumers detect drain with `if (entry.drainEndsAt) { /* draining */ }`. - /skill.md detail block: no Available bullet on active offers; only draining offers get a "Drain ends at" bullet. - /skill.md table column renamed Available → Status; active rows show "—", draining rows show "draining · ends <RFC3339>". JSON Schema: `available` removed from required and from properties; `drainEndsAt` description updated to "Presence = draining." Tests updated to assert active entries carry NO `available` or `drainEndsAt` keys in the raw JSON, and the markdown detail block for active offers contains no Available line.

bussyjd · 2026-05-24T09:14:14Z

Superseded by bundle PR #536 — closing in favor of the consolidated merge target. Original branch and history preserved.

feat: x402 marketplace + architecture review bundle (#513-#535)

…e drain signal (re-amend of #535) drain becomes purely additive — active offers serialize identically to pre-drain main. The only new wire field is `drainEndsAt`, set on draining offers only. Consumers detect drain with `if (entry.drainEndsAt) { /* draining */ }`. No schema-breaking change for any consumer that was reading the catalog before drain landed. This re-ships an amendment that was originally pushed as commit dd89750 on `feat/drain-replaces-pause` for PR #535. The amendment didn't survive the bundle PR #536's merge into main, so the controller is shipping the un-amended `Available bool` shape today. - ServiceCatalogEntry: remove `Available bool`; keep `DrainEndsAt string omitempty` - service-catalog.schema.json: drop `available` from `required` + `properties` - buildServiceCatalogJSON: stop setting Available; only set DrainEndsAt on drain - buildSkillCatalogMarkdown: rename `Available` table column to `Status` (active rows show `—`; draining rows show `draining · ends <RFC3339>`). Drop the per-service `- **Available**:` bullet entirely; draining services keep only the `- **Drain ends at**:` bullet. - serviceDefWithDrain: stop setting the (already-additive) `Available *bool` on erc8004.ServiceDef during drain; signal via DrainEndsAt only. - Tests: - TestBuildServiceCatalogJSON_ExcludesNonReady: replace `services[0].Available == true` with raw-JSON map walk asserting `available` and `drainEndsAt` keys are absent on active entries. - TestBuildServiceCatalogJSON_DrainLifecycle: rewrite to raw-map walk; assert active entries have neither `available` nor `drainEndsAt`, mid-drain entries have only `drainEndsAt` (no `available`). - TestBuildRegistration{,Identity}Services_IncludesDrainMetadata: replace `svc.Available == &false` checks with `svc.Available == nil` (DrainEndsAt is now the sole drain marker). - Add TestBuildSkillCatalogMarkdown_DrainAdditiveDetail: asserts no `- **Available**:` bullet appears for any offer, that draining offers keep their `- **Drain ends at**:` bullet, and that the table header uses `Status` not `Available`.

bussyjd · 2026-05-24T08:49:43Z

Problem

Two things were broken about the legacy "pause" path:

Pause was a route on/off switch masquerading as "pause your business."
obol.org/paused: "true" made the controller delete the HTTPRoute
immediately. From a remote x402 buyer's perspective that's
indistinguishable from a crash — and ERC-8004 reputation scorers
that watch a seller's /.well-known/agent-registration.json see an
abrupt disappearance with no advertised wind-down.
obol sell stop was broken. It patched status.conditions[Ready]=False,
which the controller overwrote on the next reconcile. The CLI looked
like it worked; in practice the offer stayed live.

Design

Replace pause with a real drain:

New spec fields advertise the wind-down via discovery before the
route disappears, so external observers can react gracefully.
The HTTPRoute + payment gate stay up during the grace window so
buyers can complete in-flight payments.
After the grace period expires, the controller tears down the route
and marks Draining=False reason=Drained. The CR stays — obol sell delete is still the canonical removal command.

Pure-additive wire shape

Drain is purely additive in the catalog. Active offers serialize
identically to pre-drain releases: no new fields, no shape change. The
only new wire surface is drainEndsAt, which is set on draining offers
only. Consumers detect drain with:

if(entry.drainEndsAt){/* draining; migrate before this time */}

There is no available field. Presence of drainEndsAt is the signal.
This was an explicit design review outcome (commit dd89750): a
separate boolean was redundant and would have been a schema-breaking
change for strict consumers. Now there is zero schema breakage.

API

ServiceOfferSpec:

Field	Type	Default	Behavior
`drainAt`	`*metav1.Time`	nil	When set, offer is draining.
`drainGracePeriod`	`*metav1.Duration`	`1h`	How long after `drainAt` the route stays up. `0s` tears down on the next reconcile.

ServiceOffer helpers: IsDraining(), DrainEndsAt() time.Time,
DrainExpired(now time.Time) bool.

CLI:

obol sell stop <name> -n <ns> # default: drainAt=now, 1h grace
obol sell stop <name> -n <ns> --grace 30m # custom grace
obol sell stop <name> -n <ns> --force # alias: --now; zero grace, abrupt teardown

Discovery surfaces:

/api/services.json: draining entries gain a single drainEndsAt: <RFC3339>
key. Active entries serialize unchanged.
/skill.md: per-service detail block adds a - **Drain ends at**:
bullet only for draining offers. The table gains a Status column
(active: —, draining: draining · ends <RFC3339>).

Drain lifecycle

sequenceDiagram
autonumber
participant Op as Operator
participant CR as ServiceOffer CR
participant Ctl as serviceoffer-controller
participant Disc as /skill.md +<br/>/.well-known/agent-registration.json
participant Route as HTTPRoute + x402 Middleware
participant Buyer as Remote buyer
Op->>CR: obol sell stop my-svc<br/>(patch spec.drainAt=now,<br/>drainGracePeriod=1h)
CR-->>Ctl: Update event
Ctl->>Ctl: IsDraining=true,<br/>DrainExpired=false
Ctl->>Disc: emit drainEndsAt=T+1h<br/>(no `available` field)
Ctl->>Route: KEEP UP
Ctl->>CR: Draining=True reason=Draining
Ctl->>Ctl: AddAfter(T+1h)
Buyer->>Disc: poll catalog
Disc-->>Buyer: drainEndsAt set → migrate
Buyer->>Route: in-flight paid request
Route-->>Buyer: 200 OK
Note over Ctl: ...grace period elapses...
Ctl->>Ctl: DrainExpired=true
Ctl->>Route: deleteRouteChildren()
Ctl->>CR: Draining=False reason=Drained,<br/>PaymentGateReady=False,<br/>RoutePublished=False
Op->>CR: obol sell delete (later, canonical removal)

Why ERC-8004 reputation matters

ERC-8004 makes seller reputation an on-chain signal that buyers and
discovery agents can score. An abrupt route teardown looks identical to
a process crash or upstream outage — a negative reputation event.
Advertising a planned wind-down (drainEndsAt) lets buyers and scorers
distinguish "this seller is gracefully retiring this offer" from
"this seller's infrastructure is unreliable." Even short grace windows
(a few minutes) move the signal from "outage" to "planned maintenance."

Migration

If you were setting obol.org/paused: "true" directly, the annotation
no longer has any effect. To match the old abrupt-teardown semantics:

obol sell stop <name> -n <ns> --force

For the recommended graceful behavior, drop --force and let buyers
see the wind-down via discovery.

Test plan

The legacy obol.org/paused annotation tore down HTTPRoutes immediately, which is indistinguishable from a crash to remote x402 buyers and ERC-8004 reputation scorers. obol sell stop was also broken: it patched status.conditions which the controller immediately overwrote. This replaces both with a real drain: - New ServiceOffer spec.drainAt (date-time) + spec.drainGracePeriod (duration; default 1h) mark an offer as winding down. - While draining, /skill.md and /.well-known/agent-registration.json advertise the offer with available=false and drainEndsAt set, so external discovery can react before traffic disappears. - The HTTPRoute + payment gate stay up until DrainEndsAt, letting in-flight buyers complete payments. - After the grace period, the controller tears down the route, sets Draining=False reason=Drained, and leaves the CR (delete is the canonical removal command). obol sell stop sets spec.drainAt, supports --grace <duration> and --force/--now (zero grace = abrupt teardown for behavior parity with the old annotation).

…e drain signal Design review concluded the `available` boolean was redundant — the presence of `drainEndsAt` is sufficient to signal drain state. This makes the drain wire shape purely additive: active offers serialize identically to pre-drain releases. Wire changes: - ServiceCatalogEntry.Available field removed. - DrainEndsAt is the only drain signal. Consumers detect drain with `if (entry.drainEndsAt) { /* draining */ }`. - /skill.md detail block: no Available bullet on active offers; only draining offers get a "Drain ends at" bullet. - /skill.md table column renamed Available → Status; active rows show "—", draining rows show "draining · ends <RFC3339>". JSON Schema: `available` removed from required and from properties; `drainEndsAt` description updated to "Presence = draining." Tests updated to assert active entries carry NO `available` or `drainEndsAt` keys in the raw JSON, and the markdown detail block for active offers contains no Available line.

bussyjd · 2026-05-24T09:14:14Z

Superseded by bundle PR #536 — closing in favor of the consolidated merge target. Original branch and history preserved.

feat: x402 marketplace + architecture review bundle (#513-#535)

…e drain signal (re-amend of #535) drain becomes purely additive — active offers serialize identically to pre-drain main. The only new wire field is `drainEndsAt`, set on draining offers only. Consumers detect drain with `if (entry.drainEndsAt) { /* draining */ }`. No schema-breaking change for any consumer that was reading the catalog before drain landed. This re-ships an amendment that was originally pushed as commit dd89750 on `feat/drain-replaces-pause` for PR #535. The amendment didn't survive the bundle PR #536's merge into main, so the controller is shipping the un-amended `Available bool` shape today. - ServiceCatalogEntry: remove `Available bool`; keep `DrainEndsAt string omitempty` - service-catalog.schema.json: drop `available` from `required` + `properties` - buildServiceCatalogJSON: stop setting Available; only set DrainEndsAt on drain - buildSkillCatalogMarkdown: rename `Available` table column to `Status` (active rows show `—`; draining rows show `draining · ends <RFC3339>`). Drop the per-service `- **Available**:` bullet entirely; draining services keep only the `- **Drain ends at**:` bullet. - serviceDefWithDrain: stop setting the (already-additive) `Available *bool` on erc8004.ServiceDef during drain; signal via DrainEndsAt only. - Tests: - TestBuildServiceCatalogJSON_ExcludesNonReady: replace `services[0].Available == true` with raw-JSON map walk asserting `available` and `drainEndsAt` keys are absent on active entries. - TestBuildServiceCatalogJSON_DrainLifecycle: rewrite to raw-map walk; assert active entries have neither `available` nor `drainEndsAt`, mid-drain entries have only `drainEndsAt` (no `available`). - TestBuildRegistration{,Identity}Services_IncludesDrainMetadata: replace `svc.Available == &false` checks with `svc.Available == nil` (DrainEndsAt is now the sole drain marker). - Add TestBuildSkillCatalogMarkdown_DrainAdditiveDetail: asserts no `- **Available**:` bullet appears for any offer, that draining offers keep their `- **Drain ends at**:` bullet, and that the table header uses `Status` not `Available`.

bussyjd · 2026-05-24T08:49:43Z

Problem

Two things were broken about the legacy "pause" path:

Pause was a route on/off switch masquerading as "pause your business."
obol.org/paused: "true" made the controller delete the HTTPRoute
immediately. From a remote x402 buyer's perspective that's
indistinguishable from a crash — and ERC-8004 reputation scorers
that watch a seller's /.well-known/agent-registration.json see an
abrupt disappearance with no advertised wind-down.
obol sell stop was broken. It patched status.conditions[Ready]=False,
which the controller overwrote on the next reconcile. The CLI looked
like it worked; in practice the offer stayed live.

Design

Replace pause with a real drain:

New spec fields advertise the wind-down via discovery before the
route disappears, so external observers can react gracefully.
The HTTPRoute + payment gate stay up during the grace window so
buyers can complete in-flight payments.
After the grace period expires, the controller tears down the route
and marks Draining=False reason=Drained. The CR stays — obol sell delete is still the canonical removal command.

Pure-additive wire shape

Drain is purely additive in the catalog. Active offers serialize
identically to pre-drain releases: no new fields, no shape change. The
only new wire surface is drainEndsAt, which is set on draining offers
only. Consumers detect drain with:

if(entry.drainEndsAt){/* draining; migrate before this time */}

There is no available field. Presence of drainEndsAt is the signal.
This was an explicit design review outcome (commit dd89750): a
separate boolean was redundant and would have been a schema-breaking
change for strict consumers. Now there is zero schema breakage.

API

ServiceOfferSpec:

Field	Type	Default	Behavior
`drainAt`	`*metav1.Time`	nil	When set, offer is draining.
`drainGracePeriod`	`*metav1.Duration`	`1h`	How long after `drainAt` the route stays up. `0s` tears down on the next reconcile.

ServiceOffer helpers: IsDraining(), DrainEndsAt() time.Time,
DrainExpired(now time.Time) bool.

CLI:

obol sell stop <name> -n <ns> # default: drainAt=now, 1h grace
obol sell stop <name> -n <ns> --grace 30m # custom grace
obol sell stop <name> -n <ns> --force # alias: --now; zero grace, abrupt teardown

Discovery surfaces:

/api/services.json: draining entries gain a single drainEndsAt: <RFC3339>
key. Active entries serialize unchanged.
/skill.md: per-service detail block adds a - **Drain ends at**:
bullet only for draining offers. The table gains a Status column
(active: —, draining: draining · ends <RFC3339>).

Drain lifecycle

sequenceDiagram
autonumber
participant Op as Operator
participant CR as ServiceOffer CR
participant Ctl as serviceoffer-controller
participant Disc as /skill.md +<br/>/.well-known/agent-registration.json
participant Route as HTTPRoute + x402 Middleware
participant Buyer as Remote buyer
Op->>CR: obol sell stop my-svc<br/>(patch spec.drainAt=now,<br/>drainGracePeriod=1h)
CR-->>Ctl: Update event
Ctl->>Ctl: IsDraining=true,<br/>DrainExpired=false
Ctl->>Disc: emit drainEndsAt=T+1h<br/>(no `available` field)
Ctl->>Route: KEEP UP
Ctl->>CR: Draining=True reason=Draining
Ctl->>Ctl: AddAfter(T+1h)
Buyer->>Disc: poll catalog
Disc-->>Buyer: drainEndsAt set → migrate
Buyer->>Route: in-flight paid request
Route-->>Buyer: 200 OK
Note over Ctl: ...grace period elapses...
Ctl->>Ctl: DrainExpired=true
Ctl->>Route: deleteRouteChildren()
Ctl->>CR: Draining=False reason=Drained,<br/>PaymentGateReady=False,<br/>RoutePublished=False
Op->>CR: obol sell delete (later, canonical removal)

Why ERC-8004 reputation matters

ERC-8004 makes seller reputation an on-chain signal that buyers and
discovery agents can score. An abrupt route teardown looks identical to
a process crash or upstream outage — a negative reputation event.
Advertising a planned wind-down (drainEndsAt) lets buyers and scorers
distinguish "this seller is gracefully retiring this offer" from
"this seller's infrastructure is unreliable." Even short grace windows
(a few minutes) move the signal from "outage" to "planned maintenance."

Migration

If you were setting obol.org/paused: "true" directly, the annotation
no longer has any effect. To match the old abrupt-teardown semantics:

obol sell stop <name> -n <ns> --force

For the recommended graceful behavior, drop --force and let buyers
see the wind-down via discovery.

Test plan

The legacy obol.org/paused annotation tore down HTTPRoutes immediately, which is indistinguishable from a crash to remote x402 buyers and ERC-8004 reputation scorers. obol sell stop was also broken: it patched status.conditions which the controller immediately overwrote. This replaces both with a real drain: - New ServiceOffer spec.drainAt (date-time) + spec.drainGracePeriod (duration; default 1h) mark an offer as winding down. - While draining, /skill.md and /.well-known/agent-registration.json advertise the offer with available=false and drainEndsAt set, so external discovery can react before traffic disappears. - The HTTPRoute + payment gate stay up until DrainEndsAt, letting in-flight buyers complete payments. - After the grace period, the controller tears down the route, sets Draining=False reason=Drained, and leaves the CR (delete is the canonical removal command). obol sell stop sets spec.drainAt, supports --grace <duration> and --force/--now (zero grace = abrupt teardown for behavior parity with the old annotation).

…e drain signal Design review concluded the `available` boolean was redundant — the presence of `drainEndsAt` is sufficient to signal drain state. This makes the drain wire shape purely additive: active offers serialize identically to pre-drain releases. Wire changes: - ServiceCatalogEntry.Available field removed. - DrainEndsAt is the only drain signal. Consumers detect drain with `if (entry.drainEndsAt) { /* draining */ }`. - /skill.md detail block: no Available bullet on active offers; only draining offers get a "Drain ends at" bullet. - /skill.md table column renamed Available → Status; active rows show "—", draining rows show "draining · ends <RFC3339>". JSON Schema: `available` removed from required and from properties; `drainEndsAt` description updated to "Presence = draining." Tests updated to assert active entries carry NO `available` or `drainEndsAt` keys in the raw JSON, and the markdown detail block for active offers contains no Available line.

bussyjd · 2026-05-24T09:14:14Z

Superseded by bundle PR #536 — closing in favor of the consolidated merge target. Original branch and history preserved.

feat: x402 marketplace + architecture review bundle (#513-#535)

…e drain signal (re-amend of #535) drain becomes purely additive — active offers serialize identically to pre-drain main. The only new wire field is `drainEndsAt`, set on draining offers only. Consumers detect drain with `if (entry.drainEndsAt) { /* draining */ }`. No schema-breaking change for any consumer that was reading the catalog before drain landed. This re-ships an amendment that was originally pushed as commit dd89750 on `feat/drain-replaces-pause` for PR #535. The amendment didn't survive the bundle PR #536's merge into main, so the controller is shipping the un-amended `Available bool` shape today. - ServiceCatalogEntry: remove `Available bool`; keep `DrainEndsAt string omitempty` - service-catalog.schema.json: drop `available` from `required` + `properties` - buildServiceCatalogJSON: stop setting Available; only set DrainEndsAt on drain - buildSkillCatalogMarkdown: rename `Available` table column to `Status` (active rows show `—`; draining rows show `draining · ends <RFC3339>`). Drop the per-service `- **Available**:` bullet entirely; draining services keep only the `- **Drain ends at**:` bullet. - serviceDefWithDrain: stop setting the (already-additive) `Available *bool` on erc8004.ServiceDef during drain; signal via DrainEndsAt only. - Tests: - TestBuildServiceCatalogJSON_ExcludesNonReady: replace `services[0].Available == true` with raw-JSON map walk asserting `available` and `drainEndsAt` keys are absent on active entries. - TestBuildServiceCatalogJSON_DrainLifecycle: rewrite to raw-map walk; assert active entries have neither `available` nor `drainEndsAt`, mid-drain entries have only `drainEndsAt` (no `available`). - TestBuildRegistration{,Identity}Services_IncludesDrainMetadata: replace `svc.Available == &false` checks with `svc.Available == nil` (DrainEndsAt is now the sole drain marker). - Add TestBuildSkillCatalogMarkdown_DrainAdditiveDetail: asserts no `- **Available**:` bullet appears for any offer, that draining offers keep their `- **Drain ends at**:` bullet, and that the table header uses `Status` not `Available`.

bussyjd added 2 commits May 24, 2026 12:49

bussyjd mentioned this pull request May 24, 2026
feat: x402 marketplace + architecture review bundle (#513-#535) #536
Merged
6 tasks

bussyjd closed this May 24, 2026

bussyjd added a commit that referenced this pull request May 24, 2026
Merge pull request#536from ObolNetwork/feat/marketplace-bundle
acccbbe
feat: x402 marketplace + architecture review bundle (#513-#535)

bussyjd mentioned this pull request May 25, 2026
fix(monetize): drop available, use drainEndsAt as sole drain signal #548
Closed
6 tasks

OisinKyne deleted the feat/drain-replaces-pause branch July 1, 2026 12:33

bussyjd added 2 commits May 24, 2026 12:49

bussyjd mentioned this pull request May 24, 2026
feat: x402 marketplace + architecture review bundle (#513-#535) #536
Merged
6 tasks

bussyjd closed this May 24, 2026

bussyjd added a commit that referenced this pull request May 24, 2026
Merge pull request#536from ObolNetwork/feat/marketplace-bundle
acccbbe
feat: x402 marketplace + architecture review bundle (#513-#535)

bussyjd mentioned this pull request May 25, 2026
fix(monetize): drop available, use drainEndsAt as sole drain signal #548
Closed
6 tasks

OisinKyne deleted the feat/drain-replaces-pause branch July 1, 2026 12:33

bussyjd added 2 commits May 24, 2026 12:49

bussyjd mentioned this pull request May 24, 2026
feat: x402 marketplace + architecture review bundle (#513-#535) #536
Merged
6 tasks

bussyjd closed this May 24, 2026

bussyjd added a commit that referenced this pull request May 24, 2026
Merge pull request#536from ObolNetwork/feat/marketplace-bundle
acccbbe
feat: x402 marketplace + architecture review bundle (#513-#535)

bussyjd mentioned this pull request May 25, 2026
fix(monetize): drop available, use drainEndsAt as sole drain signal #548
Closed
6 tasks

OisinKyne deleted the feat/drain-replaces-pause branch July 1, 2026 12:33

bussyjd added 2 commits May 24, 2026 12:49

bussyjd mentioned this pull request May 24, 2026
feat: x402 marketplace + architecture review bundle (#513-#535) #536
Merged
6 tasks

bussyjd closed this May 24, 2026

bussyjd added a commit that referenced this pull request May 24, 2026
Merge pull request#536from ObolNetwork/feat/marketplace-bundle
acccbbe
feat: x402 marketplace + architecture review bundle (#513-#535)

bussyjd mentioned this pull request May 25, 2026
fix(monetize): drop available, use drainEndsAt as sole drain signal #548
Closed
6 tasks

OisinKyne deleted the feat/drain-replaces-pause branch July 1, 2026 12:33

bussyjd added 2 commits May 24, 2026 12:49

bussyjd mentioned this pull request May 24, 2026
feat: x402 marketplace + architecture review bundle (#513-#535) #536
Merged
6 tasks

bussyjd closed this May 24, 2026

bussyjd added a commit that referenced this pull request May 24, 2026
Merge pull request#536from ObolNetwork/feat/marketplace-bundle
acccbbe
feat: x402 marketplace + architecture review bundle (#513-#535)

bussyjd mentioned this pull request May 25, 2026
fix(monetize): drop available, use drainEndsAt as sole drain signal #548
Closed
6 tasks

OisinKyne deleted the feat/drain-replaces-pause branch July 1, 2026 12:33

bussyjd added 2 commits May 24, 2026 12:49

bussyjd mentioned this pull request May 24, 2026
feat: x402 marketplace + architecture review bundle (#513-#535) #536
Merged
6 tasks

bussyjd closed this May 24, 2026

bussyjd added a commit that referenced this pull request May 24, 2026
Merge pull request#536from ObolNetwork/feat/marketplace-bundle
acccbbe
feat: x402 marketplace + architecture review bundle (#513-#535)

bussyjd mentioned this pull request May 25, 2026
fix(monetize): drop available, use drainEndsAt as sole drain signal #548
Closed
6 tasks

OisinKyne deleted the feat/drain-replaces-pause branch July 1, 2026 12:33

bussyjd added 2 commits May 24, 2026 12:49

bussyjd mentioned this pull request May 24, 2026
feat: x402 marketplace + architecture review bundle (#513-#535) #536
Merged
6 tasks

bussyjd closed this May 24, 2026

bussyjd added a commit that referenced this pull request May 24, 2026
Merge pull request#536from ObolNetwork/feat/marketplace-bundle
acccbbe
feat: x402 marketplace + architecture review bundle (#513-#535)

bussyjd mentioned this pull request May 25, 2026
fix(monetize): drop available, use drainEndsAt as sole drain signal #548
Closed
6 tasks

OisinKyne deleted the feat/drain-replaces-pause branch July 1, 2026 12:33

bussyjd added 2 commits May 24, 2026 12:49

bussyjd mentioned this pull request May 24, 2026
feat: x402 marketplace + architecture review bundle (#513-#535) #536
Merged
6 tasks

bussyjd closed this May 24, 2026

bussyjd added a commit that referenced this pull request May 24, 2026
Merge pull request#536from ObolNetwork/feat/marketplace-bundle
acccbbe
feat: x402 marketplace + architecture review bundle (#513-#535)

bussyjd mentioned this pull request May 25, 2026
fix(monetize): drop available, use drainEndsAt as sole drain signal #548
Closed
6 tasks

OisinKyne deleted the feat/drain-replaces-pause branch July 1, 2026 12:33

Uh oh!

Conversation

bussyjd commented May 24, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Design

Pure-additive wire shape

API

Drain lifecycle

Why ERC-8004 reputation matters

Migration

Test plan

Uh oh!

bussyjd commented May 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

bussyjd commented May 24, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Design

Pure-additive wire shape

API

Drain lifecycle

Why ERC-8004 reputation matters

Migration

Test plan

Uh oh!

bussyjd commented May 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

bussyjd commented May 24, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Design

Pure-additive wire shape

API

Drain lifecycle

Why ERC-8004 reputation matters

Migration

Test plan

Uh oh!

bussyjd commented May 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

bussyjd commented May 24, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Design

Pure-additive wire shape

API

Drain lifecycle

Why ERC-8004 reputation matters

Migration

bussyjd commented May 24, 2026•
edited
Loading

bussyjd commented May 24, 2026•
edited
Loading

bussyjd commented May 24, 2026•
edited
Loading

bussyjd commented May 24, 2026•
edited
Loading

bussyjd commented May 24, 2026•
edited
Loading

bussyjd commented May 24, 2026•
edited
Loading