P130 — AIEP — SaaS Runtime Binding Manifest

Publication Date: 2026-03-13 Status: Open Source Prior Art Disclosure Licence: Apache License 2.0 Author/Organisation: Phatfella Ltd Schema: AIEP_OS_SPEC_TEMPLATE v1.0.1 — https://aiep.dev/schemas/aiep-os-spec-template/v1.0.1

Framework Context

[0001] This disclosure operates within an Architected Instruction and Evidence Protocol (AIEP) environment as defined in United Kingdom patent application number GB2519711.2, filed 20 November 2025, and GB2519798.9, filed 20 November 2025, the entire contents of which are incorporated herein by reference.

[0002] The present disclosure specifies the canonical set of infrastructure bindings that constitute a compliant AIEP SaaS runtime host deployed on the Cloudflare Workers platform. It extends the general Cloudflare deployment blueprint defined in P68 to the specific binding topology required for an AIEP evidence-governed AI assistant product.

Field of the Disclosure

[0003] This disclosure relates to cloud-native AI SaaS deployments on serverless edge platforms that provide governed evidence ingestion, substrate continuity, semantic vector retrieval, session persistence, object storage, and secure credential management as first-class infrastructure bindings rather than library dependencies.

[0004] More particularly, the disclosure concerns the formal declaration of binding types, binding identifiers, secret handling conventions, and optional binding patterns that together constitute the minimum compliant AIEP SaaS runtime environment — such that any compliant implementation of AIEP-governed AI can be verified to provide or absent the specified bindings.

Background

[0005] A governed AI SaaS product built on AIEP requires multiple infrastructure subsystems to function correctly. These include: a relational database for the evidence ledger; a key-value store for session state; object storage for mirror artefacts; a vector index for semantic source retrieval; AI inference and embedding via a managed binding; Durable Object instances for stateful substrate continuity; billing integration; and HMAC-based API key security. Selecting, configuring, and wiring these bindings correctly is a critical deployment step that is architecturally significant and non-trivial.

[0006] Existing deployment documentation treats infrastructure bindings as operational configuration detail. No prior specification defines a normative binding manifest that: (a) names each binding with a canonical identifier; (b) specifies the Cloudflare Workers binding type for each; (c) distinguishes required from optional bindings; (d) specifies the security handling obligations for each secret binding; and (e) documents the AIEP justification for each binding in terms of the protocol specifications it supports.

Summary of the Disclosure

[0007] A compliant AIEP SaaS Runtime Binding Manifest declares the following required bindings:

[0008] A compliant AIEP SaaS Runtime Binding Manifest declares the following optional bindings:

[0009] A compliant AIEP SaaS Runtime Binding Manifest declares the following secret bindings, which must never appear in wrangler.toml plaintext and must be injected via wrangler secret put:

[0010] The PIEA_API_KEY_SECRET binding implements the HMAC key-hashing defence against rainbow-table attacks on the API key store. On each API key verification, the supplied key is HMAC-SHA256-hashed with PIEA_API_KEY_SECRET and compared against the stored hash. The raw key value is never written to the D1 database. If PIEA_API_KEY_SECRET is absent at runtime, the worker must reject all API key authentication requests with a 503 status and log a configuration error.

[0011] The VectorizeIndex binding, when present, activates the semantic retrieval path. The index is pre-populated with embedding vectors for Learning List sources using the embedding model referenced by the PIEA_EMBED_MODEL environment variable. When absent, the worker falls back to keyword-based source retrieval. The vector dimensions and metric are not configurable at runtime — they are fixed at index creation time and must match dimensions=768, metric=cosine for compatibility with the embedding models specified.

Detailed Description

[0012] Environment Interface Declaration. The canonical TypeScript interface for the binding manifest is:

interface Env {
  // Required — relational
  PIEA_LEDGER: D1Database;
  // Required — object storage
  PIEA_MIRRORS: R2Bucket;
  // Required — key-value session state
  PIEA_SESSIONS: KVNamespace;
  // Required — AI inference + embedding
  AI: unknown;  // typed at runtime as WorkersAI
  // Required — substrate continuity
  PRESENCE_SUBSTRATE: DurableObjectNamespace;
  // Required — environment + model config
  PIEA_MODEL: string;
  PIEA_ENV: string;
  PIEA_EMBED_MODEL: string;
  // Required secrets — must be injected via wrangler secret put
  PIEA_ADMIN_KEY: string;
  STRIPE_SECRET_KEY: string;
  STRIPE_WEBHOOK_SECRET: string;
  // Required secret — HMAC key for API key hashing
  PIEA_API_KEY_SECRET?: string;  // optional type; absence must be detected at runtime
  // Optional — semantic retrieval
  PIEA_VECTORS?: VectorizeIndex;
  // Optional — augmentation endpoints
  SEARXNG_BASE_URL?: string;
  FORECAST_API_BASE?: string;
  // Optional — Zero Trust
  CLOUDFLARE_ACCESS_TEAM?: string;
}

[0013] D1 Schema Obligations. The PIEA_LEDGER D1 database must contain at minimum: a sessions table keyed on session_id; a messages table keyed on response_id with foreign key to sessions; an evidence_artefacts table keyed on artefact_id; a dissent_records table keyed on dissent_id; and a api_keys table keyed on key_hash. Schema migrations must be run via wrangler d1 migrations apply and versioned in the repository alongside the binding manifest.

[0014] R2 Bucket Layout. Mirror snapshots are stored in PIEA_MIRRORS under the key pattern mirrors/{mirror_slug}/{snapshot_hash}.json. Ingested external mirror manifests are stored under mirrors/ingested/{origin_domain}/{manifest_hash}.json. No retention policy is imposed by this specification; implementers must configure R2 lifecycle rules separately.

[0015] KV Namespace Layout. Session state is stored in PIEA_SESSIONS under key session:{session_id} with a configurable TTL (default 86400 seconds — 24 hours). Presence substrate event buffers are stored under key presence:{session_id}:buffer and cleared on successful reconnection delivery.

[0016] Durable Object Class Binding. The PRESENCE_SUBSTRATE binding must reference a Durable Object class named PresenceSubstrate implementing the DurableObject interface. Each Durable Object instance corresponds to one substrate session. The binding must be declared in wrangler.toml as:

[[durable_objects.bindings]]
name = "PRESENCE_SUBSTRATE"
class_name = "PresenceSubstrate"

[0017] Distinction from P68 (Cloudflare Deployment Blueprint). P68 specifies the general pattern for deploying any AIEP product on Cloudflare Workers, covering route structure, wrangler.toml conventions, and environment variable patterns. P130 specifies the product-specific binding manifest for a governed AI assistant product and defines the security obligations for each secret binding. P68 is a generic blueprint; P130 is a normative manifest for a specific AIEP product class.