From f56b708e6fe42701e131c02d9cd5b63c34a0e84d Mon Sep 17 00:00:00 2001 From: James Kurz Date: Tue, 18 Aug 2026 11:44:12 -0400 Subject: [PATCH 1/6] rfc: propose Clockwork commerce service adoption --- ...-08-clockwork-commerce-service-adoption.md | 190 ++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 rfcs/2026-08-clockwork-commerce-service-adoption.md diff --git a/rfcs/2026-08-clockwork-commerce-service-adoption.md b/rfcs/2026-08-clockwork-commerce-service-adoption.md new file mode 100644 index 0000000..b0da4ff --- /dev/null +++ b/rfcs/2026-08-clockwork-commerce-service-adoption.md @@ -0,0 +1,190 @@ +# RFC: Adopt Clockwork as Fil One's commerce service + +**Status:** Proposal +**Author:** [James Kurz](https://github.com/jameskurz-filecoin) +**Date:** 2026-08-18 + +## TL;DR + +I propose that Fil One adopt +[Clockwork](https://github.com/fil-one/clockwork) as a standalone service for +commerce and commercial operations. + +Clockwork would own the customer, partner, and operator workflows around +agreements, quotes, POCs, orders, billing, renewals, and offboarding. The +existing Fil One product would continue to own storage resources, raw usage, +and provisioning. Billing authority would move only through an explicit +account/domain cutover. We would connect the two through a small, explicit API +and event boundary rather than merge Clockwork into the Fil One monorepo. + +Merging this RFC would approve the direction and an integration phase. It would +not authorize production migration or billing cutover. + +## Why + +Fil One's commercial workflow crosses product code, Stripe, HubSpot, provider +dashboards, documents, and manual coordination. That works for individual +transactions but makes it hard to answer basic operational questions reliably: + +- Who owns the customer and organization identity? +- Which quote, order, entitlement, invoice, and payment belong together? +- Who is allowed to change pricing or approve an exception? +- Which system should write to Stripe, provisioning, or CRM? +- How do we reconcile and recover after a partial failure? + +Clockwork was built to make those relationships explicit. It provides one +customer, partner, and internal-operator product around the same commercial +records, with idempotent workflows, audit history, generated documents, and +provider boundaries. + +The implementation now exists and can be evaluated as a product. The remaining +question is whether we want it to become part of Fil One and invest in the real +integration. + +## Proposal + +1. **Adopt Clockwork as an adjacent service.** Keep its repository, database, + deployment, and release lifecycle separate from the storage control plane. +2. **Keep one authority for each fact and side effect.** Existing Fil One + systems remain authoritative until a specific domain and account are + deliberately cut over. We do not dual-write Stripe, usage, provisioning, or + CRM. +3. **Reuse existing identifiers.** Clockwork attaches Fil One organization, + tenant, Stripe, entitlement, and provider IDs. It does not recreate an + organization because an email or domain happens to match. +4. **Integrate through signed, versioned, idempotent messages.** Transport + success is not business success; both services retain enough information to + retry and reconcile. +5. **Roll out incrementally.** First observe, then shadow, then move one + authority for a small cohort. Existing PAYG billing can remain on its current + path until we have evidence that moving it is worthwhile and safe. + +## Service boundary + +| Area | Proposed authority | +| --- | --- | +| Authentication | Fil One Auth0 remains the identity authority for existing users. Clockwork receives a verified subject mapping; email matching is not authorization. | +| Organizations and tenants | Fil One organization and tenant IDs remain the product identity. Clockwork owns the related commercial account and roles. | +| Products, resources, and raw usage | Fil One owns provisionable capability, storage resources, entitlements, and raw measurements. | +| Pricing, agreements, quotes, and orders | Clockwork owns approved commercial configuration and workflow. Accepted lines map to versioned Fil One product capabilities. | +| Stripe and billing | The current integration remains authoritative at first. Exactly one service writes each customer, subscription, meter, invoice, or payment domain after an explicit cutover. | +| Provisioning | Clockwork sends an approved command; Fil One owns resource state and returns accepted and terminal outcomes. | +| HubSpot | Existing integrations keep their current fields until field-level ownership is agreed. Clockwork publishes only allow-listed commercial events. | +| Support | The support provider owns tickets. Clockwork reads safe support signals unless a separate write boundary is approved. | +| Audit | Each service keeps its own domain audit history and links records with correlation and provider IDs. | +| Migration | Fil One remains source authority until a per-account cutover. Clockwork owns migration-run, mapping, and projection evidence. | + +The field-level design is already documented in Clockwork's +[adjacent-service integration boundary](https://github.com/fil-one/clockwork/blob/55b4082d380e086b29da7e76f4e060d19cbb49a6/docs/adjacent-service-integration.md). + +## Integration sequence + +### 1. Connect identity and organizations + +Map Auth0 issuer and subject to the Clockwork user, and map each Fil One +organization to a Clockwork account. Missing or ambiguous mappings fail closed. +We should decide whether this is federation or an explicit account-link step +after reviewing the current Auth0 setup. + +### 2. Shadow the existing product + +Import a pinned snapshot and consume real signed events without allowing +Clockwork to write to Stripe, usage, provisioning, or HubSpot. Compare users, +organizations, products, customers, subscriptions, usage, entitlements, +invoices, and provider objects. + +### 3. Pilot one bounded path + +Start with a small non-production cohort and one commercial path. My suggested +first candidate is a net-new annual or partner-assisted order, because it avoids +moving an existing PAYG subscription. Rehearse retries, duplicates, +out-of-order events, reconciliation, and rollback before enabling the provider +effect. + +### 4. Expand by domain + +Move additional accounts or authority domains only after the prior cohort has +zero unexplained money, usage, entitlement, or tenant variance. A rollback +restores the previous routing owner and replays retained events; it does not +delete provider or audit facts. + +## What exists today + +The reviewed revision is +[`55b4082`](https://github.com/fil-one/clockwork/tree/55b4082d380e086b29da7e76f4e060d19cbb49a6). + +- The [live guided demo](https://clockwork-commerce-demo.netlify.app/) exercises + customer, partner, and internal-operator workflows with resettable demo data. +- The serial demo suite passed 15 of 15 Playwright checks, including + quote-to-order, + price-book approval, queue refresh, partner work, customer settings, and + sandbox payment. +- The web suite passed 1,659 unit tests before two deployment follow-ups; the + follow-ups passed focused proxy, payment, and hydration tests. The database + gate exercised 45 pgTAP files and 896 assertions. +- Formatting, lint, types, generated-contract checks, traceability, security + checks, and the production build passed locally. A separate remote smoke + passed against the live Netlify deployment. +- GitHub Actions did not start because of the organization's current + billing/spend limit. That needs to be restored before hosted checks can be a + production requirement. + +The demo is evidence of the product and deterministic workflows, not evidence +that real providers are active. Production identity mapping, machine +authentication, provider accounts, reconciliation, and migration are not wired +yet. They are the work proposed by this RFC. + +## Before production + +The integration should not launch until: + +- identity and organization mapping is unambiguous; +- the service API has explicit machine authentication; +- there is one verified writer for each external effect; +- cross-tenant, duplicate, delayed, reordered, and failed-message cases pass + across the real Fil One boundary; +- cutover and rollback have been rehearsed for the pilot cohort; +- money, usage, entitlement, and provider objects reconcile with no unexplained + variance; and +- normal service basics are in place: an owning team, production hosting, + telemetry/on-call, backups, repository protections, and production-use + licensing. + +## Alternatives + +### Put the workflows in the Fil One monorepo + +This reduces one deployment but couples a large commercial domain and its +providers to the storage control plane. It also makes the migration authority +boundary less clear. I do not think the trade is worthwhile. + +### Continue with the current distributed process + +This avoids integration work but leaves the customer journey and reconciliation +spread across systems and manual process. It does not solve the problem +Clockwork was built for. + +### Buy a commerce platform + +We could run a focused comparison if the team believes a vendor covers the +whole scope. We would still need Fil One-specific identity, usage, entitlement, +provisioning, and reconciliation integration, so feature overlap alone is not a +replacement for this boundary. + +## Decisions needed + +1. Do we want Clockwork to become Fil One's commerce service? +2. Which team should own it after adoption? + +Those are the decisions needed to accept the direction. The integration phase +can then settle whether identity uses federation or account linking, which +bounded path pilots first, and where the production service runs. + +## References + +- [Clockwork repository](https://github.com/fil-one/clockwork) +- [Reviewed Clockwork revision](https://github.com/fil-one/clockwork/tree/55b4082d380e086b29da7e76f4e060d19cbb49a6) +- [Live demo](https://clockwork-commerce-demo.netlify.app/) +- [Product specification](https://github.com/fil-one/clockwork/blob/55b4082d380e086b29da7e76f4e060d19cbb49a6/commerce_platform_spec.md) +- [Adjacent-service integration boundary](https://github.com/fil-one/clockwork/blob/55b4082d380e086b29da7e76f4e060d19cbb49a6/docs/adjacent-service-integration.md) +- [External activation gates](https://github.com/fil-one/clockwork/blob/55b4082d380e086b29da7e76f4e060d19cbb49a6/docs/external-gates.md) From f3e494809dd83fa23438d8fccf647b873e5f0197 Mon Sep 17 00:00:00 2001 From: jameskurz-filecoin Date: Wed, 19 Aug 2026 11:59:01 -0400 Subject: [PATCH 2/6] Rewrite Clockwork RFC so the team can actually evaluate it Alan asked what Clockwork is, who it is for, whether we sell it, why we did not buy a vendor, and what engineering would be on the hook for. This version answers those in order and shrinks the ask to a demo plus a yes/no/buy-instead decision. --- ...-08-clockwork-commerce-service-adoption.md | 301 ++++++++---------- 1 file changed, 127 insertions(+), 174 deletions(-) diff --git a/rfcs/2026-08-clockwork-commerce-service-adoption.md b/rfcs/2026-08-clockwork-commerce-service-adoption.md index b0da4ff..7d22e22 100644 --- a/rfcs/2026-08-clockwork-commerce-service-adoption.md +++ b/rfcs/2026-08-clockwork-commerce-service-adoption.md @@ -1,190 +1,143 @@ -# RFC: Adopt Clockwork as Fil One's commerce service +# RFC: Should engineering take on Clockwork? **Status:** Proposal **Author:** [James Kurz](https://github.com/jameskurz-filecoin) -**Date:** 2026-08-18 +**Audience:** Fil One engineers +**Date:** 2026-08-19 ## TL;DR -I propose that Fil One adopt -[Clockwork](https://github.com/fil-one/clockwork) as a standalone service for -commerce and commercial operations. - -Clockwork would own the customer, partner, and operator workflows around -agreements, quotes, POCs, orders, billing, renewals, and offboarding. The -existing Fil One product would continue to own storage resources, raw usage, -and provisioning. Billing authority would move only through an explicit -account/domain cutover. We would connect the two through a small, explicit API -and event boundary rather than merge Clockwork into the Fil One monorepo. - -Merging this RFC would approve the direction and an integration phase. It would -not authorize production migration or billing cutover. - -## Why - -Fil One's commercial workflow crosses product code, Stripe, HubSpot, provider -dashboards, documents, and manual coordination. That works for individual -transactions but makes it hard to answer basic operational questions reliably: - -- Who owns the customer and organization identity? -- Which quote, order, entitlement, invoice, and payment belong together? -- Who is allowed to change pricing or approve an exception? -- Which system should write to Stripe, provisioning, or CRM? -- How do we reconcile and recover after a partial failure? - -Clockwork was built to make those relationships explicit. It provides one -customer, partner, and internal-operator product around the same commercial -records, with idempotent workflows, audit history, generated documents, and -provider boundaries. - -The implementation now exists and can be evaluated as a product. The remaining -question is whether we want it to become part of Fil One and invest in the real -integration. - -## Proposal - -1. **Adopt Clockwork as an adjacent service.** Keep its repository, database, - deployment, and release lifecycle separate from the storage control plane. -2. **Keep one authority for each fact and side effect.** Existing Fil One - systems remain authoritative until a specific domain and account are - deliberately cut over. We do not dual-write Stripe, usage, provisioning, or - CRM. -3. **Reuse existing identifiers.** Clockwork attaches Fil One organization, - tenant, Stripe, entitlement, and provider IDs. It does not recreate an - organization because an email or domain happens to match. -4. **Integrate through signed, versioned, idempotent messages.** Transport - success is not business success; both services retain enough information to - retry and reconcile. -5. **Roll out incrementally.** First observe, then shadow, then move one - authority for a small cohort. Existing PAYG billing can remain on its current - path until we have evidence that moving it is worthwhile and safe. - -## Service boundary - -| Area | Proposed authority | -| --- | --- | -| Authentication | Fil One Auth0 remains the identity authority for existing users. Clockwork receives a verified subject mapping; email matching is not authorization. | -| Organizations and tenants | Fil One organization and tenant IDs remain the product identity. Clockwork owns the related commercial account and roles. | -| Products, resources, and raw usage | Fil One owns provisionable capability, storage resources, entitlements, and raw measurements. | -| Pricing, agreements, quotes, and orders | Clockwork owns approved commercial configuration and workflow. Accepted lines map to versioned Fil One product capabilities. | -| Stripe and billing | The current integration remains authoritative at first. Exactly one service writes each customer, subscription, meter, invoice, or payment domain after an explicit cutover. | -| Provisioning | Clockwork sends an approved command; Fil One owns resource state and returns accepted and terminal outcomes. | -| HubSpot | Existing integrations keep their current fields until field-level ownership is agreed. Clockwork publishes only allow-listed commercial events. | -| Support | The support provider owns tickets. Clockwork reads safe support signals unless a separate write boundary is approved. | -| Audit | Each service keeps its own domain audit history and links records with correlation and provider IDs. | -| Migration | Fil One remains source authority until a per-account cutover. Clockwork owns migration-run, mapping, and projection evidence. | - -The field-level design is already documented in Clockwork's -[adjacent-service integration boundary](https://github.com/fil-one/clockwork/blob/55b4082d380e086b29da7e76f4e060d19cbb49a6/docs/adjacent-service-integration.md). - -## Integration sequence - -### 1. Connect identity and organizations - -Map Auth0 issuer and subject to the Clockwork user, and map each Fil One -organization to a Clockwork account. Missing or ambiguous mappings fail closed. -We should decide whether this is federation or an explicit account-link step -after reviewing the current Auth0 setup. - -### 2. Shadow the existing product - -Import a pinned snapshot and consume real signed events without allowing -Clockwork to write to Stripe, usage, provisioning, or HubSpot. Compare users, -organizations, products, customers, subscriptions, usage, entitlements, -invoices, and provider objects. - -### 3. Pilot one bounded path - -Start with a small non-production cohort and one commercial path. My suggested -first candidate is a net-new annual or partner-assisted order, because it avoids -moving an existing PAYG subscription. Rehearse retries, duplicates, -out-of-order events, reconciliation, and rollback before enabling the provider -effect. - -### 4. Expand by domain - -Move additional accounts or authority domains only after the prior cohort has -zero unexplained money, usage, entitlement, or tenant variance. A rollback -restores the previous routing owner and replays retained events; it does not -delete provider or audit facts. +Clockwork is a web app I built. It is not a vendor product and we would not +sell it. It is a quote-to-cash portal for Filecoin Foundation: quotes, orders, +partners, invoices, back office. + +I would like the engineering team to look at it, watch a demo, and then decide +whether we own it. This RFC is that question. It is not a request to cut over +billing or replace Stripe. + +Alan is right that we might be better off buying something. I want that on the +table. + +## What Clockwork is + +A Next.js app, Postgres (Supabase), Stripe, and its own login (currently +WorkOS). Repo: [fil-one/clockwork](https://github.com/fil-one/clockwork). +Demo: https://clockwork-commerce-demo.netlify.app/ — I will put the password in +the FF 1Password vault. + +Who it is for: + +- **Us (FF).** Sales, partnerships, finance, anyone who currently chases a deal + through email and PDFs. +- **Customers and partners, later.** A portal where they can see a quote, + accept an order, pay an invoice. Not a SKU we sell. + +Who would own the code if we say yes: **engineering**. Uptime, bugs, security, +features. That is the expensive part. It does not mean engineering becomes the +people who talk to customers. + +It was written by me, with a lot of AI assistance. Treat it as an unreviewed +codebase that happens to have a working demo, not as a finished internal +platform. + +Start here, not the `docs/` folder: the README, then the live demo. Skip +`docs/release-candidate-report.md`. That file is not a good introduction. + +## Why I built it + +Today a Fil One commercial deal is spread across HubSpot, Stripe, Google Docs, +and people. Fine for one-off pay-as-you-go. Painful for annual contracts, +partners, and "which quote became which invoice." + +I wanted one place where: + +- a quote has line items that map to Fil One products ("100 TB in eu-central-3") +- accepting the quote becomes an order +- the order is what we provision +- invoices and payments attach to that order +- a partner can see the deals they brought + +Stripe still charges the card. Fil One still creates the bucket. Clockwork +would be the commercial record in the middle. + +## What I am not claiming + +- We are not selling Clockwork. +- We are not cutting over existing PAYG customers. +- We are not giving Clockwork permission to write to Stripe, Auth0, or Forge + until a later, explicit decision. +- WorkOS is not a new company-wide identity system. Clockwork used it because + that is how I stood the demo up. Fil One users live in Auth0. If we keep + Clockwork, we either federate Auth0 into it or rip WorkOS out. I have not + done that work. + +## How it would sit next to Fil One + +``` +Customer / partner browser + │ + ▼ + Clockwork (quotes, orders, invoices, partner view) + │ "please provision this SKU for org X" + ▼ + Fil One API (Auth0, tenants, buckets, usage) + │ + ▼ + Forge / Ingot (actual storage) +``` + +Stripe: only one system writes for a given customer. Today that system is Fil +One. It stays that way until we deliberately move a customer. + +"Accepted line" just means a line item on an accepted quote. Example: +`object-storage / 100TB / eu-central-3` on the quote has to match a real Fil +One product, or the order stops before anyone provisions. + +There is no finished Fil One ↔ Clockwork machine API. Clockwork has an internal +OpenAPI for its own UI. The integration API is the work this RFC would +authorize us to design, not something already shipped. + +Existing Fil One users would need to be linked on purpose. Matching on email +is not good enough. New signups later would go through whatever we decide +after the demo. So yes: a one-time migration of existing accounts, and an +ongoing path for new ones. Neither is designed yet. ## What exists today -The reviewed revision is -[`55b4082`](https://github.com/fil-one/clockwork/tree/55b4082d380e086b29da7e76f4e060d19cbb49a6). - -- The [live guided demo](https://clockwork-commerce-demo.netlify.app/) exercises - customer, partner, and internal-operator workflows with resettable demo data. -- The serial demo suite passed 15 of 15 Playwright checks, including - quote-to-order, - price-book approval, queue refresh, partner work, customer settings, and - sandbox payment. -- The web suite passed 1,659 unit tests before two deployment follow-ups; the - follow-ups passed focused proxy, payment, and hydration tests. The database - gate exercised 45 pgTAP files and 896 assertions. -- Formatting, lint, types, generated-contract checks, traceability, security - checks, and the production build passed locally. A separate remote smoke - passed against the live Netlify deployment. -- GitHub Actions did not start because of the organization's current - billing/spend limit. That needs to be restored before hosted checks can be a - production requirement. - -The demo is evidence of the product and deterministic workflows, not evidence -that real providers are active. Production identity mapping, machine -authentication, provider accounts, reconciliation, and migration are not wired -yet. They are the work proposed by this RFC. - -## Before production - -The integration should not launch until: - -- identity and organization mapping is unambiguous; -- the service API has explicit machine authentication; -- there is one verified writer for each external effect; -- cross-tenant, duplicate, delayed, reordered, and failed-message cases pass - across the real Fil One boundary; -- cutover and rollback have been rehearsed for the pilot cohort; -- money, usage, entitlement, and provider objects reconcile with no unexplained - variance; and -- normal service basics are in place: an owning team, production hosting, - telemetry/on-call, backups, repository protections, and production-use - licensing. - -## Alternatives - -### Put the workflows in the Fil One monorepo - -This reduces one deployment but couples a large commercial domain and its -providers to the storage control plane. It also makes the migration authority -boundary less clear. I do not think the trade is worthwhile. - -### Continue with the current distributed process - -This avoids integration work but leaves the customer journey and reconciliation -spread across systems and manual process. It does not solve the problem -Clockwork was built for. - -### Buy a commerce platform - -We could run a focused comparison if the team believes a vendor covers the -whole scope. We would still need Fil One-specific identity, usage, entitlement, -provisioning, and reconciliation integration, so feature overlap alone is not a -replacement for this boundary. +- A clickable demo of customer, partner, and internal-operator screens. +- A lot of tests in that repo. They prove the demo workflows, not production + Stripe / Auth0 / Forge. +- GitHub Actions is currently blocked on the org billing limit. -## Decisions needed +## The real decision + +Engineering would be taking on a sizable TypeScript app that I built largely +solo. Benefits: commercial team and partners get a portal; quotes, orders, and +invoices live in one place; we stop reconciling spreadsheets. + +Costs: we own bugs, security, Stripe edge cases, and every feature request +from sales. That competes with storage work. Buying Chargebee / Stripe Billing ++ HubSpot might cover most of it with less code. I do not have a vendor bake-off +yet. If the team would rather go that way, that is a valid outcome of this RFC. + +I would like: -1. Do we want Clockwork to become Fil One's commerce service? -2. Which team should own it after adoption? +1. A 45-minute demo for the team. I will schedule it. +2. A follow-up technical walkthrough of the repo for whoever would own it. +3. A yes / no / buy-instead decision after that, not before. + +Until then, please do not treat Clockwork as an incoming dependency of POSIX, +Forge, or the console. + +## Decisions needed -Those are the decisions needed to accept the direction. The integration phase -can then settle whether identity uses federation or account linking, which -bounded path pilots first, and where the production service runs. +1. Are we willing to spend a demo plus a tech review on this? +2. After that: own it, kill it, or trial a vendor? +3. If we own it, who? This means on-call and security, not who talks to + customers. ## References -- [Clockwork repository](https://github.com/fil-one/clockwork) -- [Reviewed Clockwork revision](https://github.com/fil-one/clockwork/tree/55b4082d380e086b29da7e76f4e060d19cbb49a6) +- [Clockwork repo](https://github.com/fil-one/clockwork) - [Live demo](https://clockwork-commerce-demo.netlify.app/) -- [Product specification](https://github.com/fil-one/clockwork/blob/55b4082d380e086b29da7e76f4e060d19cbb49a6/commerce_platform_spec.md) -- [Adjacent-service integration boundary](https://github.com/fil-one/clockwork/blob/55b4082d380e086b29da7e76f4e060d19cbb49a6/docs/adjacent-service-integration.md) -- [External activation gates](https://github.com/fil-one/clockwork/blob/55b4082d380e086b29da7e76f4e060d19cbb49a6/docs/external-gates.md) +- [README](https://github.com/fil-one/clockwork/blob/main/README.md) From a3ce4a380f6efdde22b668baf4bc33b6ce514d2c Mon Sep 17 00:00:00 2001 From: jameskurz-filecoin Date: Wed, 19 Aug 2026 12:14:31 -0400 Subject: [PATCH 3/6] Rewrite Clockwork RFC from the actual demo and auth code The demo is a password plus a persona cookie, not WorkOS. WorkOS is how the real app would log people in. Fil One stays on Auth0. A vendor is an equal outcome, not a consolation prize. --- ...-08-clockwork-commerce-service-adoption.md | 170 ++++++++---------- 1 file changed, 78 insertions(+), 92 deletions(-) diff --git a/rfcs/2026-08-clockwork-commerce-service-adoption.md b/rfcs/2026-08-clockwork-commerce-service-adoption.md index 7d22e22..e408f79 100644 --- a/rfcs/2026-08-clockwork-commerce-service-adoption.md +++ b/rfcs/2026-08-clockwork-commerce-service-adoption.md @@ -7,124 +7,111 @@ ## TL;DR -Clockwork is a web app I built. It is not a vendor product and we would not -sell it. It is a quote-to-cash portal for Filecoin Foundation: quotes, orders, -partners, invoices, back office. +Clockwork is a quote-to-cash web app I built for Filecoin Foundation. We would +not sell it. Off-the-shelf is allowed to win. -I would like the engineering team to look at it, watch a demo, and then decide -whether we own it. This RFC is that question. It is not a request to cut over -billing or replace Stripe. - -Alan is right that we might be better off buying something. I want that on the -table. +I would like the team to click through the demo, then decide: **own it, kill +it, or trial a vendor.** This RFC is that question. It is not a billing +cutover, not a Fil One API design, and not a dependency of POSIX or the +console. ## What Clockwork is -A Next.js app, Postgres (Supabase), Stripe, and its own login (currently -WorkOS). Repo: [fil-one/clockwork](https://github.com/fil-one/clockwork). -Demo: https://clockwork-commerce-demo.netlify.app/ — I will put the password in -the FF 1Password vault. +A TypeScript monorepo I built, with a lot of AI assistance. Repo: +[fil-one/clockwork](https://github.com/fil-one/clockwork). Who it is for: -- **Us (FF).** Sales, partnerships, finance, anyone who currently chases a deal - through email and PDFs. +- **Us (FF), first.** Sales, partnerships, finance — anyone who currently + chases a deal through email, PDFs, HubSpot, and Stripe. - **Customers and partners, later.** A portal where they can see a quote, accept an order, pay an invoice. Not a SKU we sell. +Sales and finance have not agreed they will use this. That is part of what +the demo is for. + Who would own the code if we say yes: **engineering**. Uptime, bugs, security, -features. That is the expensive part. It does not mean engineering becomes the -people who talk to customers. +features. Not who talks to customers. -It was written by me, with a lot of AI assistance. Treat it as an unreviewed -codebase that happens to have a working demo, not as a finished internal -platform. +Treat it as an unreviewed codebase with a working demo, not a finished +internal platform. -Start here, not the `docs/` folder: the README, then the live demo. Skip -`docs/release-candidate-report.md`. That file is not a good introduction. +Start at the README, then the live demo. Skip `docs/`, especially +`docs/release-candidate-report.md`. The README line “one artifact chain, no +re-keying” is brochure language. Ignore it. -## Why I built it +## What you can click today + +Hosted demo: https://clockwork-commerce-demo.netlify.app/ + +That site is Next.js on Netlify with fake data in Netlify Blobs. It does +**not** run Postgres, Stripe, or WorkOS. There is no production on-call. + +The gate is a shared password, then a persona picker. Password lives in the +Netlify env (`CLOCKWORK_DEMO_ACCESS_PASSWORD`). I will put it in the FF +1Password vault. It is not in the git repo. + +Flagship path: `/demo` → **Start as Mara Voss** → follow **Review the issued +version and proceed to acceptance** on quote `Q-2026-0312` → accept the order +with PO `PO-DEMO-0312` → confirm the PDF → **Restore demo data** when you are +done (draft and prod share the same blob store). + +## Login, Stripe, Fil One — as they actually are -Today a Fil One commercial deal is spread across HubSpot, Stripe, Google Docs, -and people. Fine for one-off pay-as-you-go. Painful for annual contracts, -partners, and "which quote became which invoice." +I read the code. Three different systems: -I wanted one place where: +| Who | Login | What they touch | +| --- | --- | --- | +| Fil One customers | Auth0, Fil One console | Buckets, usage, today’s PAYG Stripe | +| Clockwork **demo** visitors | Shared password + persona cookie | Fake quotes/orders. No WorkOS. No Stripe. | +| Clockwork **if we ran it for real** | WorkOS AuthKit (ADR 0004) | Clockwork’s own DB. Stripe SDK exists (`StripeFinanceGateway`) but is not the writer for Fil One customers. | -- a quote has line items that map to Fil One products ("100 TB in eu-central-3") -- accepting the quote becomes an order -- the order is what we provision -- invoices and payments attach to that order -- a partner can see the deals they brought +Clockwork does not sit in front of Auth0. Fil One does not proxy Clockwork. +People who buy storage still log into Fil One. People who issue quotes would +log into Clockwork. -Stripe still charges the card. Fil One still creates the bucket. Clockwork -would be the commercial record in the middle. +If we keep Clockwork, we either federate Auth0 into WorkOS or rip WorkOS out. +That work is not done. + +Stripe: only one system writes for a given customer. Today that is Fil One. It +stays that way until we deliberately move a customer. The demo never calls +Stripe. + +There is no Fil One ↔ Clockwork machine API. There are HTTP ports and fakes +pointing at unnamed URLs. The integration API is not in scope of this RFC. Do +not block POSIX or the console on it. + +## Why I built it + +A Fil One commercial deal is spread across HubSpot, Stripe, Google Docs, and +people. Fine for one-off PAYG. Painful for annual contracts, partners, and +“which quote became which invoice.” + +I wanted one place where a quote’s line items map to Fil One products +(“100 TB in eu-central-3”), accepting the quote becomes an order, and invoices +attach to that order. + +That is a product wish, not a reason we have to own this repo. +Chargebee, or Stripe Billing + HubSpot, might cover most of it with less code. +I have not done that comparison. A vendor is allowed to win. ## What I am not claiming - We are not selling Clockwork. - We are not cutting over existing PAYG customers. -- We are not giving Clockwork permission to write to Stripe, Auth0, or Forge - until a later, explicit decision. -- WorkOS is not a new company-wide identity system. Clockwork used it because - that is how I stood the demo up. Fil One users live in Auth0. If we keep - Clockwork, we either federate Auth0 into it or rip WorkOS out. I have not - done that work. - -## How it would sit next to Fil One - -``` -Customer / partner browser - │ - ▼ - Clockwork (quotes, orders, invoices, partner view) - │ "please provision this SKU for org X" - ▼ - Fil One API (Auth0, tenants, buckets, usage) - │ - ▼ - Forge / Ingot (actual storage) -``` - -Stripe: only one system writes for a given customer. Today that system is Fil -One. It stays that way until we deliberately move a customer. - -"Accepted line" just means a line item on an accepted quote. Example: -`object-storage / 100TB / eu-central-3` on the quote has to match a real Fil -One product, or the order stops before anyone provisions. - -There is no finished Fil One ↔ Clockwork machine API. Clockwork has an internal -OpenAPI for its own UI. The integration API is the work this RFC would -authorize us to design, not something already shipped. - -Existing Fil One users would need to be linked on purpose. Matching on email -is not good enough. New signups later would go through whatever we decide -after the demo. So yes: a one-time migration of existing accounts, and an -ongoing path for new ones. Neither is designed yet. - -## What exists today - -- A clickable demo of customer, partner, and internal-operator screens. -- A lot of tests in that repo. They prove the demo workflows, not production - Stripe / Auth0 / Forge. -- GitHub Actions is currently blocked on the org billing limit. +- We are not asking Fil One to proxy Auth0 or Stripe through Clockwork. +- We are not asking anyone to own this on the basis of this document alone. ## The real decision -Engineering would be taking on a sizable TypeScript app that I built largely -solo. Benefits: commercial team and partners get a portal; quotes, orders, and -invoices live in one place; we stop reconciling spreadsheets. - -Costs: we own bugs, security, Stripe edge cases, and every feature request -from sales. That competes with storage work. Buying Chargebee / Stripe Billing -+ HubSpot might cover most of it with less code. I do not have a vendor bake-off -yet. If the team would rather go that way, that is a valid outcome of this RFC. +Engineering would be taking on Next.js, Supabase, WorkOS, a Stripe adapter, +Trigger.dev, and every sales feature request. That competes with storage work. I would like: -1. A 45-minute demo for the team. I will schedule it. -2. A follow-up technical walkthrough of the repo for whoever would own it. -3. A yes / no / buy-instead decision after that, not before. +1. A 45-minute demo. I will schedule it. +2. A follow-up walkthrough of the repo for whoever would own it. +3. A yes / no / **trial a vendor** decision after that. Until then, please do not treat Clockwork as an incoming dependency of POSIX, Forge, or the console. @@ -133,11 +120,10 @@ Forge, or the console. 1. Are we willing to spend a demo plus a tech review on this? 2. After that: own it, kill it, or trial a vendor? -3. If we own it, who? This means on-call and security, not who talks to - customers. +3. If we own it, who is on-call? ## References - [Clockwork repo](https://github.com/fil-one/clockwork) - [Live demo](https://clockwork-commerce-demo.netlify.app/) -- [README](https://github.com/fil-one/clockwork/blob/main/README.md) +- [README rewrite PR](https://github.com/fil-one/clockwork/pull/35) From 67620b3c2f9d6aecd5a30375e950f9114cbb03c4 Mon Sep 17 00:00:00 2001 From: jameskurz-filecoin Date: Wed, 19 Aug 2026 12:22:56 -0400 Subject: [PATCH 4/6] Name the Clockwork demo as the ask, and the stacks as they really are Demo is Netlify plus a password. Production would be Vercel, WorkOS, and Postgres. Fil One stays on Auth0. A vendor is allowed to win. --- ...-08-clockwork-commerce-service-adoption.md | 29 +++++++++---------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/rfcs/2026-08-clockwork-commerce-service-adoption.md b/rfcs/2026-08-clockwork-commerce-service-adoption.md index e408f79..92af886 100644 --- a/rfcs/2026-08-clockwork-commerce-service-adoption.md +++ b/rfcs/2026-08-clockwork-commerce-service-adoption.md @@ -1,4 +1,4 @@ -# RFC: Should engineering take on Clockwork? +# RFC: Spend 45 minutes on the Clockwork demo before anyone talks about owning it **Status:** Proposal **Author:** [James Kurz](https://github.com/jameskurz-filecoin) @@ -36,9 +36,8 @@ features. Not who talks to customers. Treat it as an unreviewed codebase with a working demo, not a finished internal platform. -Start at the README, then the live demo. Skip `docs/`, especially -`docs/release-candidate-report.md`. The README line “one artifact chain, no -re-keying” is brochure language. Ignore it. +Start at the live demo. Skip `docs/`, especially +`docs/release-candidate-report.md`. ## What you can click today @@ -58,28 +57,26 @@ done (draft and prod share the same blob store). ## Login, Stripe, Fil One — as they actually are -I read the code. Three different systems: - | Who | Login | What they touch | | --- | --- | --- | | Fil One customers | Auth0, Fil One console | Buckets, usage, today’s PAYG Stripe | | Clockwork **demo** visitors | Shared password + persona cookie | Fake quotes/orders. No WorkOS. No Stripe. | -| Clockwork **if we ran it for real** | WorkOS AuthKit (ADR 0004) | Clockwork’s own DB. Stripe SDK exists (`StripeFinanceGateway`) but is not the writer for Fil One customers. | +| Clockwork **if we ran it for real** | WorkOS AuthKit | Clockwork’s own DB. A Stripe adapter exists in the repo; it is not the writer for Fil One customers. | Clockwork does not sit in front of Auth0. Fil One does not proxy Clockwork. People who buy storage still log into Fil One. People who issue quotes would log into Clockwork. -If we keep Clockwork, we either federate Auth0 into WorkOS or rip WorkOS out. -That work is not done. +Fil One stays on Auth0. Clockwork-if-real stays on WorkOS. This RFC does not +choose federation. Stripe: only one system writes for a given customer. Today that is Fil One. It stays that way until we deliberately move a customer. The demo never calls Stripe. -There is no Fil One ↔ Clockwork machine API. There are HTTP ports and fakes -pointing at unnamed URLs. The integration API is not in scope of this RFC. Do -not block POSIX or the console on it. +There is no Fil One API. Provisioning and the other integrations are typed +ports with fakes, not a client against a live Fil One URL. This RFC does not +ask us to design one. ## Why I built it @@ -104,8 +101,9 @@ I have not done that comparison. A vendor is allowed to win. ## The real decision -Engineering would be taking on Next.js, Supabase, WorkOS, a Stripe adapter, -Trigger.dev, and every sales feature request. That competes with storage work. +If we owned it, production would be Next.js on Vercel with Supabase Postgres, +WorkOS AuthKit, a Stripe adapter, and Trigger.dev. The Netlify demo is not +that stack. Owning it competes with storage work. I would like: @@ -113,8 +111,7 @@ I would like: 2. A follow-up walkthrough of the repo for whoever would own it. 3. A yes / no / **trial a vendor** decision after that. -Until then, please do not treat Clockwork as an incoming dependency of POSIX, -Forge, or the console. +Until then, Clockwork is not a dependency of anything else. ## Decisions needed From e1bfc76fe94634f32a295e4b8d229deff652960e Mon Sep 17 00:00:00 2001 From: jameskurz-filecoin Date: Wed, 19 Aug 2026 12:27:00 -0400 Subject: [PATCH 5/6] WIP local: lead Clockwork with the client journey, not service boundaries Not pushed. Demo first, then pilot / buy / kill. PAYG stays on Fil One. --- ...-08-clockwork-commerce-service-adoption.md | 160 ++++++++---------- 1 file changed, 72 insertions(+), 88 deletions(-) diff --git a/rfcs/2026-08-clockwork-commerce-service-adoption.md b/rfcs/2026-08-clockwork-commerce-service-adoption.md index 92af886..0c30252 100644 --- a/rfcs/2026-08-clockwork-commerce-service-adoption.md +++ b/rfcs/2026-08-clockwork-commerce-service-adoption.md @@ -1,4 +1,4 @@ -# RFC: Spend 45 minutes on the Clockwork demo before anyone talks about owning it +# RFC: Use Clockwork to unblock the quote-to-order journey we show clients **Status:** Proposal **Author:** [James Kurz](https://github.com/jameskurz-filecoin) @@ -7,120 +7,104 @@ ## TL;DR -Clockwork is a quote-to-cash web app I built for Filecoin Foundation. We would -not sell it. Off-the-shelf is allowed to win. +Enterprise and channel conversations still cannot walk one path from a tailored +quote to approval, order, provisioning, and billing. That work lives in HubSpot, +Stripe, PDFs, and people. It makes Fil One look less finished than the storage +product, and it blocks deals we should be able to close or demo. -I would like the team to click through the demo, then decide: **own it, kill -it, or trial a vendor.** This RFC is that question. It is not a billing -cutover, not a Fil One API design, and not a dependency of POSIX or the -console. +[Clockwork](https://github.com/fil-one/clockwork) is a working prototype of that +journey. We would not sell it as a product. This RFC asks whether the customer +value is worth a **real pilot** — and if so, whether we own this app, or buy +something that covers the same path. -## What Clockwork is +Off-the-shelf is allowed to win. Doing nothing is not, if we keep promising +partners a coherent commercial experience we cannot show. -A TypeScript monorepo I built, with a lot of AI assistance. Repo: -[fil-one/clockwork](https://github.com/fil-one/clockwork). +**Decision after a 45-minute demo:** own a pilot, trial a vendor, or kill it. +Not a billing cutover, not a Fil One rewrite. -Who it is for: +## Who is stuck today -- **Us (FF), first.** Sales, partnerships, finance — anyone who currently - chases a deal through email, PDFs, HubSpot, and Stripe. -- **Customers and partners, later.** A portal where they can see a quote, - accept an order, pay an invoice. Not a SKU we sell. +- **A prospective customer** who needs an annual or custom quote, not self-serve + PAYG. Today that is email and a PDF. They cannot see the quote, accept it, or + watch it become an account. +- **A channel partner** who should register a deal, price it, and see commission + without a spreadsheet. +- **Us (sales, partnerships, finance)** who cannot point at one record and say + which quote became which order, which invoice, which tenant. -Sales and finance have not agreed they will use this. That is part of what -the demo is for. +PAYG in the Fil One console is fine. This is everything next to it. -Who would own the code if we say yes: **engineering**. Uptime, bugs, security, -features. Not who talks to customers. +Clockwork is for all three audiences. The hosted demo lets you click each of +them. Sales and finance have not signed off that they will live in it; the demo +is how we find that out. -Treat it as an unreviewed codebase with a working demo, not a finished -internal platform. +## What you can show a client tomorrow -Start at the live demo. Skip `docs/`, especially -`docs/release-candidate-report.md`. +https://clockwork-commerce-demo.netlify.app/ -## What you can click today +Shared password (Netlify env; I will put it in the FF 1Password vault before +we sit down — it is not in git). Then pick a persona. The site is fake data on +Netlify. It does not talk to Stripe, WorkOS, Auth0, or Forge. -Hosted demo: https://clockwork-commerce-demo.netlify.app/ +Walk this: -That site is Next.js on Netlify with fake data in Netlify Blobs. It does -**not** run Postgres, Stripe, or WorkOS. There is no production on-call. +1. `/demo` → **Start as Mara Voss** (customer). +2. Open the issued annual quote and accept it (PO `PO-DEMO-0312`). +3. Download the order-form PDF. The quote flips to accepted. +4. Switch to an internal persona if you want the operator view. +5. **Restore demo data** when you are done. -The gate is a shared password, then a persona picker. Password lives in the -Netlify env (`CLOCKWORK_DEMO_ACCESS_PASSWORD`). I will put it in the FF -1Password vault. It is not in the git repo. +That is the impression I want in the room: quote → accept → order, in one +place, looking like a product. The RFC is whether we make a slice of that +true against Fil One. -Flagship path: `/demo` → **Start as Mara Voss** → follow **Review the issued -version and proceed to acceptance** on quote `Q-2026-0312` → accept the order -with PO `PO-DEMO-0312` → confirm the PDF → **Restore demo data** when you are -done (draft and prod share the same blob store). +## What Clockwork is (and is not) -## Login, Stripe, Fil One — as they actually are +A TypeScript app I built, with a lot of AI assistance. Not a vendor. Not a +SKU we sell. -| Who | Login | What they touch | -| --- | --- | --- | -| Fil One customers | Auth0, Fil One console | Buckets, usage, today’s PAYG Stripe | -| Clockwork **demo** visitors | Shared password + persona cookie | Fake quotes/orders. No WorkOS. No Stripe. | -| Clockwork **if we ran it for real** | WorkOS AuthKit | Clockwork’s own DB. A Stripe adapter exists in the repo; it is not the writer for Fil One customers. | +The **demo** is Next.js on Netlify plus a password and persona cookies. -Clockwork does not sit in front of Auth0. Fil One does not proxy Clockwork. -People who buy storage still log into Fil One. People who issue quotes would -log into Clockwork. +**If we ran it for real:** Next.js on Vercel, Supabase Postgres, WorkOS AuthKit +for Clockwork login, a Stripe adapter in-repo, Trigger.dev. Fil One customers +would still log into Fil One with Auth0. Clockwork would not sit in front of +Auth0 or become the PAYG Stripe writer. -Fil One stays on Auth0. Clockwork-if-real stays on WorkOS. This RFC does not -choose federation. +There is no Fil One API yet. Provisioning is typed ports and fakes. A pilot +would need the smallest real call: “this approved order means enable this +product for this org.” That is later work. This RFC does not design it. -Stripe: only one system writes for a given customer. Today that is Fil One. It -stays that way until we deliberately move a customer. The demo never calls -Stripe. +Engineering would own uptime, bugs, and security if we keep the app. That +competes with storage work. Name that cost before we fall in love with the +demo. -There is no Fil One API. Provisioning and the other integrations are typed -ports with fakes, not a client against a live Fil One URL. This RFC does not -ask us to design one. +## Alternatives -## Why I built it +- **Pilot Clockwork.** My lean, because we can put it in front of a client + now. Smallest next step after the demo: one non-PAYG path, no Stripe cutover, + no Auth0 federation. +- **Buy Chargebee, or Stripe Billing + HubSpot.** Allowed to win. I have not + done a bake-off. If the team would rather buy, that is a valid result of + this RFC — as long as we can still demo a coherent journey to clients. +- **Keep stitching email/PDF/HubSpot.** Cheap for engineering. Continues to + block the conversations that need a quote-to-order story. -A Fil One commercial deal is spread across HubSpot, Stripe, Google Docs, and -people. Fine for one-off PAYG. Painful for annual contracts, partners, and -“which quote became which invoice.” +## What I am not asking for -I wanted one place where a quote’s line items map to Fil One products -(“100 TB in eu-central-3”), accepting the quote becomes an order, and invoices -attach to that order. - -That is a product wish, not a reason we have to own this repo. -Chargebee, or Stripe Billing + HubSpot, might cover most of it with less code. -I have not done that comparison. A vendor is allowed to win. - -## What I am not claiming - -- We are not selling Clockwork. -- We are not cutting over existing PAYG customers. -- We are not asking Fil One to proxy Auth0 or Stripe through Clockwork. -- We are not asking anyone to own this on the basis of this document alone. - -## The real decision - -If we owned it, production would be Next.js on Vercel with Supabase Postgres, -WorkOS AuthKit, a Stripe adapter, and Trigger.dev. The Netlify demo is not -that stack. Owning it competes with storage work. - -I would like: - -1. A 45-minute demo. I will schedule it. -2. A follow-up walkthrough of the repo for whoever would own it. -3. A yes / no / **trial a vendor** decision after that. - -Until then, Clockwork is not a dependency of anything else. +- Selling Clockwork. +- Moving existing PAYG customers off Fil One Stripe. +- POSIX, Forge, or console work waiting on this. +- Anyone owning the repo on the basis of this document alone. ## Decisions needed -1. Are we willing to spend a demo plus a tech review on this? -2. After that: own it, kill it, or trial a vendor? -3. If we own it, who is on-call? +1. Sit through the demo. +2. Then: **pilot Clockwork**, **trial a vendor**, or **kill it**. +3. If we pilot: who is on-call, and what is the one customer path in scope. ## References -- [Clockwork repo](https://github.com/fil-one/clockwork) - [Live demo](https://clockwork-commerce-demo.netlify.app/) -- [README rewrite PR](https://github.com/fil-one/clockwork/pull/35) +- [Clockwork repo](https://github.com/fil-one/clockwork) +- [README rewrite (not merged)](https://github.com/fil-one/clockwork/pull/35) From 55de7dc4478dc06a8563f3e000e8da678381916f Mon Sep 17 00:00:00 2001 From: jameskurz-filecoin Date: Wed, 19 Aug 2026 12:28:52 -0400 Subject: [PATCH 6/6] WIP local: Clockwork TL;DR is the client journey plus the three-way decision --- ...-08-clockwork-commerce-service-adoption.md | 29 +++++++------------ 1 file changed, 10 insertions(+), 19 deletions(-) diff --git a/rfcs/2026-08-clockwork-commerce-service-adoption.md b/rfcs/2026-08-clockwork-commerce-service-adoption.md index 0c30252..9c792e8 100644 --- a/rfcs/2026-08-clockwork-commerce-service-adoption.md +++ b/rfcs/2026-08-clockwork-commerce-service-adoption.md @@ -13,15 +13,16 @@ Stripe, PDFs, and people. It makes Fil One look less finished than the storage product, and it blocks deals we should be able to close or demo. [Clockwork](https://github.com/fil-one/clockwork) is a working prototype of that -journey. We would not sell it as a product. This RFC asks whether the customer -value is worth a **real pilot** — and if so, whether we own this app, or buy -something that covers the same path. +journey: someone issues a quote, an approver accepts it, the customer sees an +order, and that order is what we would provision. We would not sell Clockwork. +PAYG in the Fil One console stays as it is. -Off-the-shelf is allowed to win. Doing nothing is not, if we keep promising -partners a coherent commercial experience we cannot show. +**Decision after a 45-minute demo:** pilot this app, trial a vendor (Chargebee +or Stripe Billing + HubSpot), or kill it. Off-the-shelf is allowed to win. +Doing nothing is not, if we keep showing partners a journey we cannot run. -**Decision after a 45-minute demo:** own a pilot, trial a vendor, or kill it. -Not a billing cutover, not a Fil One rewrite. +Not a billing cutover. Not a Fil One rewrite. Not anyone owning the repo from +this document alone. ## Who is stuck today @@ -33,11 +34,8 @@ Not a billing cutover, not a Fil One rewrite. - **Us (sales, partnerships, finance)** who cannot point at one record and say which quote became which order, which invoice, which tenant. -PAYG in the Fil One console is fine. This is everything next to it. - -Clockwork is for all three audiences. The hosted demo lets you click each of -them. Sales and finance have not signed off that they will live in it; the demo -is how we find that out. +Clockwork is for all three. Sales and finance have not signed off that they +will live in it; the demo is how we find that out. ## What you can show a client tomorrow @@ -90,13 +88,6 @@ demo. - **Keep stitching email/PDF/HubSpot.** Cheap for engineering. Continues to block the conversations that need a quote-to-order story. -## What I am not asking for - -- Selling Clockwork. -- Moving existing PAYG customers off Fil One Stripe. -- POSIX, Forge, or console work waiting on this. -- Anyone owning the repo on the basis of this document alone. - ## Decisions needed 1. Sit through the demo.