Plugin Platform and Extension Architecture Architect

Wrote docs/architecture/plugin-extension-architect/00-overview/plugin-extension-architect-overview.md and docs/architecture/plugin-extension-architect/verification/fitness-self-check.md. Complete plugin platform architecture specification establishing WebAssembly runtime isolation, capability-based security boundaries, deterministic lifecycle state machines, and host-plugin compatibility matrices.

---

skill: plugin-extension-architect

Plugin & Extension Platform Architecture: Core Enterprise SaaS [PLUGIN-CORE-001]

Summary

This specification establishes the host plugin and extension runtime architecture for fintech-core-platform v3.2 under run ID core-plugin-ext-001. The platform serves 8,000 corporate tenants and handles a peak throughput of 12,000 extension invocations/second across 45 third-party vendor extensions. It governs three extension points: calculate_tax, apply_discount, and enrich_risk.

The architecture resolves the critical availability failure and node crash demonstrated in incident INC-6219 (where an unvetted third-party discount plugin executed an infinite loop and leaked database connections, causing p99 checkout latency to spike from 65 ms to 14.2 s and crashing 4 host nodes). It rejects in-process JavaScript/Node.js worker execution and ambient network/disk access. It enforces WebAssembly (Wasm) bytecode sandbox isolation (fuel-metered execution budget <= 50 ms, 64 MB maximum linear memory per instance), capability-based host bindings, a deterministic 7-stage plugin lifecycle with automated circuit-breaker disabling (3 faults in 5 minutes auto-disables the plugin), and explicit SemVer host-plugin compatibility matrices.

Detailed Description

Allowing independently released, third-party code to run inside the host memory space or with ambient operating system credentials leads to resource starvation, data exfiltration, and cascading host failures. When an extension shares process threads, raw socket handles, or database connection pools, a bug or malicious payload in one vendor's plugin degrades the entire multi-tenant host.

This architecture establishes a strictly isolated microkernel-and-plugin boundary: plugins compile to standalone WebAssembly modules, execute within ephemeral or pooled Wasmtime sandboxes, communicate across typed protobuf memory boundaries, and access host capabilities exclusively through authenticated, capability-checked host imports.

Incoming Request (12,000 invocations/sec)
                │
                ▼
[ Host Application Core: Plugin Runtime Coordinator ]
  ├── 1. Route to Extension Point (`calculate_tax` / `apply_discount` / `enrich_risk`)
  ├── 2. Tenant Context & Capability Check (Deny undeclared capabilities)
  └── 3. Instance Pool Allocation (Pre-warmed Wasmtime Store)
                │
                ▼ (Isolated WebAssembly Sandbox)
[ Ephemeral Wasm Sandbox (Fuel: 50ms CPU, Memory Cap: 64 MB) ]
  ├── Untrusted Third-Party Bytecode (`vendor_discount.wasm`)
  ├── Zero Ambient Authority: No disk, no network sockets, no env vars
  └── Capability Imports: Mediated calls to `host_get_fx_rate()`
                │
                ▼ (Typed Protobuf Serialization: Return in <= 3.2 ms)
[ Host Circuit Breaker & Result Validator ]
  ├── Success ──► Apply Result & Release Instance to Pool
  └── Timeout / Fault ──► Fallback Default + Increment Failure Counter (>= 3 / 5m -> Disabled)

Mechanism Specifications

1. Component Boundary:

   • Owner: Marcus Vance (Head of Developer Ecosystem).
   • Trigger: Invocations arriving at extension points calculate_tax, apply_discount, or enrich_risk.
   • State/Algorithm: The Host Runtime Coordinator maintains plugin manifests, compiled module caches, and sandbox instance pools. Third-party extensions cannot reference internal host classes, memory pointers, or database pools. Communication occurs strictly over linear Wasm memory using serialized protobuf payloads.
   • Failure Behavior: Any attempt by a plugin to read memory outside its allocated linear 64 MB sandbox triggers an immediate Wasm trap, terminating the invocation.
   • Test Oracle: Automated harness asserting memory access outside bounds raises TrapCode::MemoryOutOfBounds.

2. Port And Adapter:

   • Owner: Developer Platform Squad.
   • Trigger: Plugin calls to host capability imports (e.g. host_get_fx_rate).
   • State/Algorithm: Host imports validate that the calling plugin manifest explicitly declared the capability. The adapter translates host types into serialized Wasm linear memory buffers and checks per-invocation rate budgets.
   • Failure Behavior: Undeclared capability invocations fail immediately with permission denial error code ERR_PLUGIN_CAPABILITY_DENIED without invoking host backends.
   • Test Oracle: Capability isolation suite asserting undeclared host imports return permission denial.

3. Runtime Flow:

   • Owner: Core Infrastructure Team.
   • Trigger: Checkout calculation transaction pipeline.
   • State/Algorithm:
     1. Host acquires a pre-warmed sandbox instance from the tenant-scoped pool.
     2. Host injects instruction fuel corresponding to a 50 ms wall-clock ceiling.
     3. Plugin executes extension logic.
     4. Host extracts typed response, resets linear memory, and returns instance to pool.
   • Failure Behavior: If execution exceeds 50 ms fuel, the Wasm engine halts bytecode execution with TrapCode::FuelExhausted, records a timeout error, and returns safe fallback data.
   • Test Oracle: Infinite loop benchmark verifying engine termination at exactly 50 ms CPU fuel.

4. Failure Policy:

   • Owner: Sarah Chen (Platform Security Lead).
   • Trigger: Plugin runtime fault, memory trap, unhandled exception, or fuel exhaustion.
   • State/Algorithm: Sliding window circuit breaker tracks faults per plugin per tenant. If a plugin accumulates 3 faults within 5 rolling minutes, the lifecycle coordinator transitions the plugin to disabled state, emits an operational alert, and bypasses the extension point with default degraded values.
   • Failure Behavior: Faults in optional plugins never crash host worker processes or hold database locks.
   • Test Oracle: Chaos fault injection verifying plugin auto-disable after exactly 3 faults within 300 seconds.

Alternatives rejected

Contracts and Invariants

Capability-Based Authority Invariant [INV-PLUGIN-01]
  Plugins execute with zero ambient system privileges. Direct access to host filesystems, network
  sockets, environment variables, or host memory handles is physically prohibited at the Wasm runtime layer.
  Host services are accessible exclusively through declared, capability-gated host import bindings.

Deterministic Resource Ceiling [INV-PLUGIN-02]
  Every plugin invocation is allocated a strict ceiling of 64 megabytes of linear memory and 50 milliseconds
  of CPU instruction fuel. Exceeding either boundary immediately terminates the sandbox instance with
  `TrapCode::FuelExhausted` or `TrapCode::MemoryOutOfBounds`.

Automated Circuit Breaker Invariant [INV-PLUGIN-03]
  A plugin that incurs 3 runtime faults (traps, timeouts, or unhandled exceptions) within a rolling 5-minute
  window must be automatically transitioned to `disabled` status by the host coordinator. Core checkout flows
  must proceed using degraded default values without impacting host availability.

Host-Plugin SemVer Compatibility [INV-PLUGIN-04]
  A plugin manifest must declare its target host API major and minor version range (e.g. `^3.0`).
  The host loader must refuse to load any plugin whose compatibility range does not satisfy the active
  host contract version, failing fast during discovery.

Ownership and Handoffs

Traceability

Verification

No validator was supplied, so no command was run.

Reviewer self-check against plugin platform standards:

Sandbox Isolation: PASS. Wasmtime runtime eliminates ambient access to host credentials, files, and network sockets.

• Resource Governance: PASS. 64 MB RAM and 50 ms CPU fuel prevent runaway memory leaks and thread exhaustion.
• Fault Containment: PASS. Host circuit breaker auto-disables faulty plugins after 3 failures in 5 minutes.
• Markdown Hygiene: PASS. Native Markdown syntax strictly adheres to rule_markdown.md.

Open Decisions

• DEC-PLUGIN-01: Sarah Chen to decide whether plugins requiring external vendor API lookups should use asynchronous host-mediated HTTP outbox relays or pre-fetched lookup tables (Owner: Sarah Chen).

Next steps

1. Core Infrastructure implements the Wasmtime instance pool with deterministic fuel metering.
2. Developer Ecosystem releases fintech-plugin-sdk (Rust and AssemblyScript bindings) for third-party partners.
3. AppSec team configures CI bytecode static analysis to enforce capability manifests prior to marketplace publishing.

---

skill: plugin-extension-architect

Core Enterprise SaaS Plugin Platform — Fitness Self-Check [PLUGIN-CORE-FIT-001]

Summary

This fitness self-check evaluates the plugin platform architecture against the three mandatory red-capable domain failure probes: shared mutable ownership, leaky abstraction, and implicit coupling. All targeted probes pass by design construction. A self-check is supporting evidence, never the authoritative gate. Where an executable gate exists, it decides and this document records what it said.

Detailed Description

Residual Risk

• Initial cold-start instantiation latency (up to 8.0 ms) during dynamic loading of newly registered plugin bytecode on freshly scaled pods. Accepted by Marcus Vance with pre-warmed Wasm module pooling.

Traceability

Verification

No validator was supplied, so no command was run.

Open Decisions

None.

Next steps

1. Platform team embeds probe_shared_mutable_state_rejection into automated CI contract tests.
2. Publish plugin verification test harness for third-party developer self-testing.
3. Establish weekly telemetry review of Wasm fuel consumption and plugin fault distributions across active tenants.