plugins/ppq architecture

Implements the PayPerQ AppWeaver model-source plugin, including encrypted workspace accounts and keys, validated model catalogs, attested local proxy lifecycle, balance preflight, approved Lightning top-ups, command and web UI handling, release metadata, documentation, and vendored build support.

Architectural role

Independent AppWeaver plugin repository whose local v0.1.0 candidate is organized around a first-party orchestration layer and a separately pinned vendored proxy. The package manifest and provider form the ai-model-source v1 contract boundary, while release guidance, documentation, provenance, and build controls keep implementation claims aligned and publication blocked pending funded live-flow verification.

Source map

• account-api.ts — Exports createPpqAccount, which creates an account through a bounded, timed PPQ request and strictly validates returned credentials.
• balance.ts — Exports fetchPpqBalance, which authenticates an API key against PPQ and accepts only a bounded strict nonnegative USD balance response.
• build.ts — Exports vendored-proxy paths and serialized build functions that fingerprint sources and Node, run npm ci with a restricted environment, and record a build marker.
• catalog.ts — Fetches, bounds, strictly validates, normalizes, caches, and refreshes PPQ models while marking dynamic-price or proxy-unsupported private models unavailable.
• db.ts — Exports workspace SQLite migrations and operations for encrypted credentials, account and key selection, settings, validated models, favorites, and recent usage.
• definition.ts — Defines the ppq command and its help, status, account, key, model, settings, and funding subcommands with required ID arguments where applicable.
• handler.ts — Dispatches PPQ commands, renders authenticated web controls, creates and imports accounts, checks balances, manages models and funding, safely rotates active credentials, and redacts failures.
• init.ts — Exports PpqPlugin, which registers plugin identity, commands, handlers, runtime context, and the ai-model-source provider and restores active proxies on initialization.
• provider.ts — Exports the ai-model-source v1 provider and workspace activation flow for state, catalog, context usage, selection, favorites, preflight, runtime configuration, activation, and deactivation.
• proxy.ts — Builds, starts, verifies, rotates, and stops one credential-bound PPQ proxy per workspace target on loopback using a strict attestation health response.
• runtime.ts — Exports PPQ context initialization, run-drain coordination, and active or explicit workspace resolution with lazy database opening.
• topup-api.ts — Exports bounded authenticated PPQ Lightning invoice creation and settlement checks with defensive normalization and fail-closed response validation.
• topup.ts — Exports requestPpqTopup, which restricts top-ups to web invocations, validates amount and invoice properties, and delegates explicit approval and settlement tracking to core payments.

Integration details

• account-api.ts — Acts as the narrow external account-provisioning adapter used by first-party orchestration.
• balance.ts — Supplies the fail-closed balance boundary used before model execution and funded-flow verification.
• build.ts — Bridges first-party lifecycle management to the pinned vendor package while preserving source and runtime provenance.
• catalog.ts — Backs the provider's ai-model-source v1 catalog surface and prevents unsupported offerings from becoming selectable.
• db.ts — Forms the workspace-scoped persistence boundary for provider state without moving proxy implementation into first-party code.
• definition.ts — Declares the user-facing command contract that the release documentation and handler behavior must match.
• handler.ts — Serves as the primary command and web orchestration layer across account, catalog, credential, and funding workflows.
• init.ts — Is the AppWeaver integration entry point and binds the package identity to its declared ai-model-source v1 capability.
• provider.ts — Implements the principal ai-model-source v1 contract and coordinates host-facing model selection with workspace proxy activation.
• proxy.ts — Keeps first-party responsibility limited to supervising and attesting the pinned proxy rather than absorbing its request-processing implementation.
• runtime.ts — Provides shared workspace and run-lifecycle infrastructure for commands, provider operations, and safe proxy restoration.
• topup-api.ts — Isolates the remote Lightning funding protocol behind strict validation for the approved payment flow.
• topup.ts — Defines the policy boundary that keeps funding user-approved, web-scoped, and mediated by core payments during live-flow verification.