Skip to content

feat(quoter-bot): add per-maturity bootstrap premium method - #174

Merged
julien-devatom merged 8 commits into
mainfrom
bootstrap-maturity-premiums-d70999
Aug 26, 2026
Merged

feat(quoter-bot): add per-maturity bootstrap premium method#174
julien-devatom merged 8 commits into
mainfrom
bootstrap-maturity-premiums-d70999

Conversation

@julien-devatom

@julien-devatom julien-devatom commented Aug 25, 2026

Copy link
Copy Markdown
Collaborator

Implements MKT-1787.

Why

Midnight books are fixed-rate, fixed-maturity. The bootstrap workflow priced every configured market off one reference with a flat static premiumBps (≤ 0), so a bot quoting several maturities lent long at short-book rates — far-maturity offers were systematically adversely selected on duration, and the only workaround was hand-tuning one bot (or entry) per maturity. MKT-1787 asks for one bot quoting all maturities with a per-maturity premium — further maturity = higher premium — making bootstrap quoting a function of market rate and maturity, with the function shape left TBD.

What

  • New optional per-entry maturityPremium config — a tagged union discriminated by shape so future shapes land without config migration ("shape TBD" resolved as an extension point). Initial linear shape: floor(premiumPerYearBps × secondsToMaturity / 31 536 000), optionally capped by inclusive maximumPremiumBps, zero at/past maturity.
  • Requested rate becomes reference + premiumBps + maturity premium, still saturating into the entry's [minimumRateBps, maximumRateBps]. The static premium stays ≤ 0 (urgency discount anchoring the short end); the maturity term is strictly positive duration compensation — long maturities can now rest above reference, which partially supersedes the TIB-2026-07-27 "only discounted offer" posture (recorded in TIB-2026-08-25, with the 07-27 banner updated).
  • Fresh time to maturity is composed beside the reference-rate read (Promise.all) only for entries that configure a premium, wired in production as SDK market.timeToMaturity(block.timestamp) — block clock, never wall clock, to stay consistent with tick/settlement math. A configured premium without its observation fails loud (BootstrapConfigurationError), and a failed maturity read propagates as the existing reference-read strategy-wide hard halt.
  • Integer flooring makes the decaying premium a step function (~1 bps per several days at typical slopes); the make layer already reconciles same-tick terms to unchanged, so a step republishes only when it moves the canonical Midnight tick.
  • Verbose diagnostics gain maturityPremiumBps and referenceRate.secondsToMaturity, so any requested rate decomposes from one record.
  • Full operator surface: config parsers (YAML + BOOTSTRAP_MARKETS), README + docs/reference.md (also fixes the stale "rejected rather than clamped" claim — the domain clamps), examples; the hardcoded-rate load check is reachability-aware (rejects only rates pinned outside the bounds at every maturity), architecture note, playground (typed round-trip, editor select/inputs, clamped reachable quote-range preview with callout, browser-boundary allowlists), typedoc.

Deliberate scope choices (redirect cheaply if the ticket intends otherwise)

  • Per-entry curve config, not one shared curve block: matches the all-per-entry bootstrap schema and keeps per-market risk caps explicit; a shared fan-out block remains a compatible follow-up.
  • Bootstrap only: ladder (quotePremiumBps) curve support is deliberately deferred; a curve-aware bootstrap next to a curve-blind ladder is called out in the TIB's future considerations.
  • No automatic rollover into next maturities (TIB-2026-07-27 non-goal preserved).

Validation

  • quoter-bot typecheck, workspace lint (0 warnings), format, knip: clean.
  • 1011 quoter-bot unit tests (68 new across domain/config/infra/application/playground) and the full workspace unit suite pass. Fork-e2e files fail locally only for the missing RPC_URL_8453 env; the playground Chromium smoke failure reproduces identically on the clean base (macOS /private/var realpath quirk) — CI is the gate for both.
  • jsdoc:check inventories the new public callables; TypeDoc builds with warnings-as-errors.
  • Example YAML and .env.example values parse through the real config parsers to the expected typed values.

🤖 Generated with Claude Code

@julien-devatom julien-devatom self-assigned this Aug 25, 2026
@linear-code

linear-code Bot commented Aug 25, 2026

Copy link
Copy Markdown

MKT-1787

@julien-devatom

Copy link
Copy Markdown
Collaborator Author

@codex review

@julien-devatom

Copy link
Copy Markdown
Collaborator Author

@prd-carapulse[bot] can you review and approve if all good

@prd-carapulse

prd-carapulse Bot commented Aug 25, 2026

Copy link
Copy Markdown
Contributor

Review posted on PR #174.

Verdict: Changes requested; not approved.
Blocker: Dead-Code fails because DEFAULT_MATURITY_PREMIUM_PER_YEAR_BPS is an unused export at bots/quoter-bot/playground/field-visibility.utils.ts:6.
CI: Lint ✅, Typecheck ✅, Dead-Code ❌, Test pending.
Local checks: blocked by Node mismatch: repository requires ^24.14.1; runtime has v26.3.0.
Action: Remove the unused export or consume it through an import, then rerun CI.

@prd-carapulse prd-carapulse Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested.

  • Required CI check Dead-Code fails: DEFAULT_MATURITY_PREMIUM_PER_YEAR_BPS is reported as an unused export at bots/quoter-bot/playground/field-visibility.utils.ts:6. Remove the export or consume it through an import; then rerun CI.
  • Local verification was blocked by the runtime Node mismatch: repository requires Node ^24.14.1, runner has Node v26.3.0.

Typecheck and lint pass; approval is blocked by the red Dead-Code check.

chatgpt-codex-connector[bot]

This comment was marked as resolved.

@julien-devatom

Copy link
Copy Markdown
Collaborator Author

Round-1 findings addressed in 43a9468: the Dead-Code failure is fixed (DEFAULT_MATURITY_PREMIUM_PER_YEAR_BPS is no longer exported) and the hardcoded-rate load check is now reachability-aware per the codex finding (entries are rejected only when pinned outside the bounds at every maturity, with new test coverage). The Node note is about the reviewer runner's own environment (repo pins ^24.14.1 via .nvmrc), nothing changed in the PR for it.

@codex review

@julien-devatom

Copy link
Copy Markdown
Collaborator Author

@prd-carapulse[bot] can you review and approve if all good

@prd-carapulse

prd-carapulse Bot commented Aug 25, 2026

Copy link
Copy Markdown
Contributor

Approved PR #174 at head 43a9468f0b49c49a913a8f36f7039e5540a9208a.

• No blocking correctness, security, or coverage issues found.
Lint, Typecheck, and Dead-Code: passed.
Test: still running; merge remains gated until it passes.
• Local tests blocked by repository Node requirement ^24.14.1; runtime has v26.3.0.

@prd-carapulse prd-carapulse Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed current head 43a9468. No blocking correctness, security, or test-coverage issues found in the maturity-premium changes. Lint, Typecheck, and Dead-Code checks pass; Test was still in progress at review time.

Reviewed by Hermes Agent.

chatgpt-codex-connector[bot]

This comment was marked as resolved.

@julien-devatom

Copy link
Copy Markdown
Collaborator Author

Codex round-2 finding addressed in a69dc9b: the playground bootstrap preview now mirrors the reachability-aware load semantics — with a maturityPremium it renders the clamped quote range reachable across maturities (near-maturity base through the capped or bound-limited far end) instead of validating the premium-free base quote.

@codex review

@julien-devatom

Copy link
Copy Markdown
Collaborator Author

@prd-carapulse[bot] can you review and approve if all good

@prd-carapulse

prd-carapulse Bot commented Aug 25, 2026

Copy link
Copy Markdown
Contributor

Approved PR #174 at head a69dc9ba7403ac173f44fd1828c5b2b3537e1ed1.

Review: No blocking correctness, security, or coverage issues found.
CI: Lint, Typecheck, Dead-Code passed. Test still running; merge remains gated.
Local checks: Blocked by Node mismatch: repo requires ^24.14.1, runner has v26.3.0.
Changes made: None.

@prd-carapulse prd-carapulse Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed current head a69dc9b. No blocking correctness, security, or test-coverage issues found in the maturity-premium changes. Lint, Typecheck, and Dead-Code pass; Test is still running and remains the merge gate. Local execution was blocked by the repository Node requirement ^24.14.1 while this runner has v26.3.0.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. 👍

Reviewed commit: a69dc9ba74

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Open in Devin Review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a69dc9ba74

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread bots/quoter-bot/src/infrastructure/bootstrap/production-bootstrap.ts Outdated
Comment thread bots/quoter-bot/src/infrastructure/bootstrap/production-bootstrap.ts Outdated
@julien-devatom

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cd9766fea7

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread bots/quoter-bot/src/config/market-collections.ts Outdated
@julien-devatom

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Hooray!

Reviewed commit: eee8caa7f7

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

@julien-devatom

Copy link
Copy Markdown
Collaborator Author

CI is green again at 09b2ff8. Since the last approvals the branch gained: two refinements from the stacked ladder work (shared maturity-read helper in src/infrastructure/maturity-read.utils.ts; reachability additionally bounded by the protocol maturity horizon via highestReachableMaturityPremiumBps) and one CI fix (ci(checks): install the pinned Foundry release directly — upstream turned foundryup into a native binary on 2026-08-25 and broke every bash foundryup run; main needs the same fix). The intermediate Test failures were that Foundry breakage plus one occurrence of the known mobile browser-smoke focus flake.

@codex review

@julien-devatom

Copy link
Copy Markdown
Collaborator Author

@prd-carapulse[bot] can you review and approve if all good

@prd-carapulse

prd-carapulse Bot commented Aug 25, 2026

Copy link
Copy Markdown
Contributor

Review posted: ⚠️ Changes requested

.github/workflows/checks.yml:52 downloads and installs Foundry from mutable tag v1.5.1 without SHA-256 or attestation verification, then runs it with sudo. This weakens the previous commit-pinned action and permits arbitrary CI binary execution if the tag or asset changes.

• Keep the action pinned, or verify the release asset digest/attestation before extraction.

• Application changes reviewed; no additional blocking issue found. Lint, Typecheck, Dead-Code, and Test pass.

Review: #174 (review)

@prd-carapulse prd-carapulse Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: .github/workflows/checks.yml:52 downloads and installs a release archive by a mutable tag without verifying its digest or attestation. This replaces the previously commit-pinned foundry-toolchain action, so a tag/asset move or compromised release path can execute arbitrary binaries with sudo in CI. Keep the action pinned or pin the release asset plus a reviewed SHA-256/attestation verification before extraction. The application changes and CI checks otherwise look good.

@julien-devatom

Copy link
Copy Markdown
Collaborator Author

Hardened per the carapulse finding in b9949db: the release download is now pinned by SHA-256 (73640b01…dcfe88, checked with sha256sum --check --strict before extraction; the digest corresponds to the asset referenced by foundry's published attestation file, linked in the step comment), and the binaries extract without sudo into an ephemeral $RUNNER_TEMP PATH entry instead of /usr/local/bin. A post-pin tag or asset move now fails the job instead of executing.

@codex review

@julien-devatom

Copy link
Copy Markdown
Collaborator Author

@prd-carapulse[bot] can you review and approve if all good

@prd-carapulse

prd-carapulse Bot commented Aug 25, 2026

Copy link
Copy Markdown
Contributor

Approved PR #174.

  • Head: b9949db2897f5bb80b5638e14a77947de739d586
  • Review: No blocking correctness, security, or coverage issues found.
  • CI hardening: Foundry archive SHA-256 verified before extraction; no sudo.
  • Checks: Lint and Dead-Code pass. Typecheck and Test still running; merge remains gated.
  • Changes made: None.

@prd-carapulse prd-carapulse Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed current head b9949db. No blocking correctness, security, or coverage issues found. The Foundry CI hardening now verifies the pinned v1.5.1 archive SHA-256 before extraction and avoids sudo. Lint and Dead-Code pass; Typecheck and Test are still in progress, so merge remains gated until both complete.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Chef's kiss.

Reviewed commit: b9949db289

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

julien-devatom and others added 7 commits August 26, 2026 09:01
Quote all configured maturities from one bot with a per-maturity premium:
an optional per-entry maturityPremium tagged union (initial linear shape)
resolves floor(premiumPerYearBps * secondsToMaturity / year), optionally
capped, on top of the static premiumBps, so further maturities quote
higher while the requested rate still saturates into the entry's hard
range. Time to maturity is read fresh each cycle via the midnight-sdk
Market.timeToMaturity on the latest Base block timestamp, composed beside
the reference-rate read; a configured premium without its observation
fails loud and halts the strategy. Verbose diagnostics decompose the
quote into reference, static premium, and maturity premium.

Implements MKT-1787; records the design and the partially superseded
discounted-offer posture in TIB-2026-08-25.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Codex review findings on the maturity-read seam: raw provider failures
now surface as the stable sanitized BootstrapAdapterError maturity-read
classification, the immutable market read is cached per market, and one
latest-block read is shared across a cycle sweep, so N maturity-enabled
entries cost about one RPC per cycle instead of 2N. The helper is shared
so the ladder follow-up composes the identical read path.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Codex finding: an uncapped curve was treated as having unbounded upside,
accepting configurations a too-shallow slope leaves permanently
floor-clamped. Midnight's touchMarket rejects maturities beyond
block.timestamp + 100 * 365 days, so highestReachableMaturityPremiumBps
resolves the premium at that horizon (the configured cap still binds
below it) and the hardcoded bounds check and bootstrap preview use the
finite reachable envelope.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@julien-devatom
julien-devatom force-pushed the bootstrap-maturity-premiums-d70999 branch from b9949db to dc0c65d Compare August 26, 2026 07:02
@julien-devatom

Copy link
Copy Markdown
Collaborator Author

All branch commits are now signed (verification.verified=true on every SHA) — history was rewritten in place with identical trees and force-pushed with lease from b9949db to dc0c65d; no content changed. CI re-runs on the new SHAs.

@codex review

@julien-devatom

Copy link
Copy Markdown
Collaborator Author

@prd-carapulse[bot] can you review and approve if all good

@prd-carapulse

prd-carapulse Bot commented Aug 26, 2026

Copy link
Copy Markdown
Contributor

Approved PR #174 at current head dc0c65d5bf8538b80535ec8c48d50615be9e9ba7.

No blocking correctness, security, or coverage issues found. Previous findings are addressed. Lint, Typecheck, and Dead-Code pass; Test remains in progress and is still the merge gate. No merge performed.

@prd-carapulse prd-carapulse Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed current head dc0c65d. No blocking correctness, security, or test-coverage issues found in the maturity-premium implementation or the Foundry CI hardening. The previously raised findings are addressed: reachability uses the finite protocol horizon, previews account for the premium range, maturity reads are typed and shared, and the archive digest is verified before extraction. Lint and Dead-Code pass; Typecheck and Test are still running and remain merge gates. Local execution was not used because this runner has Node v26.3.0 while the repository requires ^24.14.1.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dc0c65d5bf

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread bots/quoter-bot/src/config/market-collections.ts
Comment thread bots/quoter-bot/src/infrastructure/maturity-read.utils.ts Outdated
@julien-devatom

Copy link
Copy Markdown
Collaborator Author

Both round-4 findings addressed in d9659a3 (signed): the hardcoded-rate load check now tests attainable premium steps instead of the dense envelope, and the shared block-read TTL is clocked monotonically so backward wall-clock steps cannot extend it.

@codex review

@julien-devatom

Copy link
Copy Markdown
Collaborator Author

@prd-carapulse[bot] can you review and approve if all good

@prd-carapulse

prd-carapulse Bot commented Aug 26, 2026

Copy link
Copy Markdown
Contributor

Approved PR #174.

  • Head: d9659a3b294b61df874d35b1a0f9d582e608300b
  • Review: No blocking correctness, security, or coverage issues.
  • CI: Lint, Typecheck, and Dead-Code pass. Test still running and remains the merge gate.
  • Changes: None. No merge performed.

@prd-carapulse prd-carapulse Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed current head d9659a3. No blocking correctness, security, or coverage issues found. The latest attainable-premium validation and monotonic block-share-clock changes are covered by tests; diff is clean. CI: Lint, Typecheck, and Dead-Code pass; Test is still pending and remains the merge gate. No changes made; no merge performed.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: d9659a3b29

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

@julien-devatom
julien-devatom merged commit 99c7277 into main Aug 26, 2026
10 of 11 checks passed
@julien-devatom
julien-devatom deleted the bootstrap-maturity-premiums-d70999 branch August 26, 2026 12:13
julien-devatom added a commit that referenced this pull request Aug 26, 2026
…-f85533

Takes main's SHA-256-pinned direct Foundry download (PR #174) for the
checks workflow, superseding this branch's foundry-toolchain v1.9.1 bump
for the same binary-foundryup breakage.
julien-devatom added a commit that referenced this pull request Aug 27, 2026
…-f85533

Takes main's SHA-256-pinned direct Foundry download (PR #174) for the
checks workflow, superseding this branch's foundry-toolchain v1.9.1 bump
for the same binary-foundryup breakage.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant