Version: 1.0 Status: Implementation-ready draft Audience: Engineering Last updated: 2026-01-21
This folder is the canonical v1 specification for implementing webhost.systems from scratch. It consolidates product + technical requirements into a small set of normative documents with ADRs (Architecture Decision Records). If you implement only what’s in these files, you should be able to build a working v1.
Start here (overall system)
00_MASTER_SPEC.md — the single “master” engineering spec: scope, architecture, flows, core requirements, acceptance criteria.
Implement your API surface and contracts
10_API_CONTRACTS.md — normalized request/response shapes, error envelope, idempotency, pagination, invocation gateway, telemetry ingestion, and billing/webhook contracts.
Implement runtime portability
20_RUNTIME_PROVIDER_INTERFACE.md — Runtime Provider Interface (RPI) that all runtimes must implement, plus adapter guidance (including AgentCore TypeScript adapter guidance using @aws-sdk/client-bedrock-agentcore, and notes on the bedrock-agentcore tools SDK ecosystem).
Build your control-plane data layer
30_DATA_MODEL_SUPABASE.md — Supabase/PostgreSQL schema, indexes, invariants, RLS policies, retention and deletion semantics.
Lock down security and secrets
40_SECURITY_SECRETS_COMPLIANCE.md — threat model, secrets strategy requirements, telemetry integrity, webhook integrity, artifact safety, acceptance criteria.
Build metering, billing UX, and enforcement
50_OBSERVABILITY_BILLING_LIMITS.md — telemetry pipeline, aggregation model, cost estimation (estimated in v1), tier entitlements, runtime gating, limit enforcement algorithms.
Verify correctness end-to-end
60_TESTING_ACCEPTANCE.md — unit/integration/E2E test plan + release gates and system-level definition of done.
ADRs document the “why” behind major choices and define additional constraints that implementations must satisfy.
adr/ADR-0001-multi-runtime.md — Multi-runtime strategy (Cloudflare default + AgentCore premium), explicitly TypeScript-first across both runtimes (AgentCore SDKs: @aws-sdk/client-bedrock-agentcore and bedrock-agentcore).
adr/ADR-0002-supabase-control-plane.md — Supabase as control-plane backend (supersedes original Convex choice); Edge Functions for server-only logic.
adr/ADR-0003-secrets-strategy.md — No plaintext secrets in DB; provider-native secret injection; write-only secrets API.
adr/ADR-0004-telemetry-integrity.md — Deployment-scoped signed telemetry events + ownership cross-check.
adr/ADR-0005-deployment-immutability.md — Immutable deployment records + activeDeploymentId routing pointer + rollback.
adr/ADR-0006-invocation-protocol.md — Canonical invoke/v1 protocol, session semantics, and SSE streaming model.
adr/ADR-0007-entitlements-and-limits.md — Tier entitlements, runtime gating, and limit enforcement strategy.
Daily implementation progress logs live in ../progress/ (relative to this folder). These logs are non-normative and exist to track execution against this spec.
Recommended convention:
One file per day: YYYY-MM-DD.md
Include: what shipped, what changed, decisions made (with links to ADRs/spec sections), and next steps.
MUST / MUST NOT / SHOULD / MAY are used intentionally.
Control plane = auth, DB, deploy orchestration, billing, telemetry ingestion/aggregation, UI API.
Data plane = runtime provider execution environments (Cloudflare Workers/DO, AWS AgentCore).
Session IDs are opaque and runtime-specific; the control plane and clients must not parse them.
Deployments are immutable records; routing is via the agent’s single activeDeploymentId.
Minimum v1 must-haves:
Auth + tenant isolation across all endpoints.
Agent CRUD.
Immutable deployments + rollback (active pointer).
Invocation gateway with consistent invoke/v1 contract (non-streaming required; streaming recommended).
Telemetry ingestion with integrity protection (deployment-scoped signing) and ownership cross-check.
Usage aggregation by billing period + dashboard usage views.
Tier entitlements + runtime gating (AgentCore gated) + at least request-limit enforcement.
No plaintext secrets in the primary DB; secrets injected into providers.
Retention for raw telemetry/logs by tier (at minimum: raw telemetry deletion job).
E2E flow: create agent → set secrets → deploy (Cloudflare) → invoke → view usage.
Team/org/role-based access control (single-owner resources only).
Perfect cost reconciliation with provider billing exports (v1 cost is “estimated”).
Public agents / unauthenticated invocation (unless explicitly added later with API keys).
Full prompt/response storage (telemetry is numeric and metadata-focused by default).
This folder is the canonical spec. Earlier rough drafts (if any remain) are useful as background, but implementation should follow this folder.
If any contradictions are found:
Prefer 00_MASTER_SPEC.md and 10_API_CONTRACTS.md for canonical behavior.
Prefer ADRs for “why” and invariants.
Treat earlier drafts as non-normative.
WebHost.Systems is a PULSE-conforming loop under OS-010. As the hosting layer for the entire [&] ecosystem, its loop encodes the deploy → invoke → meter → bill rhythm. Unlike other loops in the portfolio it is the only one whose substrates include both Cloudflare Workers and AWS AgentCore (per ADR-0001), and its act phase is intentionally pluggable through the Runtime Provider Interface (per 20_RUNTIME_PROVIDER_INTERFACE.md).
Loop ID: webhost.deploy_invoke Loop name: WebHost.Systems Deploy/Invoke Loop Version: 1.0.0 Owner: webhost.systems Workspace scope: required
Phases (5 canonical kinds):
| Phase ID | Kind | Description |
|---|---|---|
retrieve_deployment | retrieve | Resolve agent_id → activeDeploymentId from Supabase control plane (per ADR-0005) |
route_runtime | route | Select runtime provider via RPI (Cloudflare default, AgentCore premium, others as adapters) |
act_invoke | act | Execute invoke/v1 (per ADR-0006); stream SSE response if requested; capture telemetry |
learn_telemetry | learn | Aggregate signed telemetry events; update usage counters; check tier entitlements |
consolidate_billing | consolidate | Periodic aggregation by billing period; retention pruning; cost estimation rollups |
Closure: consolidate_billing → retrieve_deployment via Supabase, guarantee eventual.
Cadence: Primary event (every invocation). Fallback periodic (billing aggregation, retention sweeps).
Substrates:
memory: graphonomous://workspace/{ws_id} (optional, for hosted MCP sidecars)
policy: delegatic://workspace/{ws_id} (tier entitlements, runtime gating)
audit: delegatic://workspace/{ws_id}/audit + Supabase telemetry table
auth: supabase://auth (Supabase Auth, shared with other Node-based products)
transport: https (invoke/v1 per ADR-0006), mcp (sidecars)
time: ticktickclock://workspace/{ws_id} (optional, for SLA enforcement)
Invariants enabled: phase_atomicity, feedback_immutability (immutable deployments per ADR-0005), append_only_audit, outcome_grounding, trace_id_propagation. The deployment-immutability invariant from ADR-0005 corresponds directly to feedback_immutability in PULSE terms.
Cross-loop connections:
usage_to_billing — consolidate_billing emits OutcomeSignal (usage rollup) to billing webhooks
entitlement_violation — route_runtime emits OutcomeSignal (gated runtime requested) to delegatic.governance.learn_drift
deploy_to_fleetprompt — optional ConsolidationEvent from consolidate_billing to fleetprompt.publish for usage-based trust signals
Why this matters: WebHost.Systems is the only loop in the portfolio with multiple swappable runtime providers in its act phase. PULSE's phase schema allows the runtime to be opaque (declared via signature and policy_check fields) — the manifest stays stable even as the RPI gains new adapters. This is the pattern other loops should follow when their act phase depends on third-party infrastructure.
See OS-010-PULSE-SPECIFICATION.md in /home/travis/ProjectAmp2/opensentience.org/docs/spec/ for the full PULSE protocol spec.