docs: floci architecture findings, connector scope correction, delivery constraints (#28)

Author: lex00

conformance/cases/60-connectors.json

@@ -4,7 +4,10 @@
     "subnetId": "subnet-00000000000000001",
     "securityGroupId": "sg-00000000000000001"
   },
-  "tags": ["documented-only"],
+  "tags": [
+    "documented-only",
+    "subset:floci"
+  ],
   "steps": [
     {
       "name": "create",
@@ -15,28 +18,48 @@
         "Name": "m80-conf-connector",
         "Configuration": {
           "VpcEgressConfiguration": {
-            "SubnetIds": ["${subnetId}"],
-            "SecurityGroupIds": ["${securityGroupId}"]
+            "SubnetIds": [
+              "${subnetId}"
+            ],
+            "SecurityGroupIds": [
+              "${securityGroupId}"
+            ]
           }
         }
       },
-      "expect": { "status": 202, "bodyMatch": { "Name": "m80-conf-connector" } },
-      "capture": { "connectorId": "Id" }
+      "expect": {
+        "status": 202,
+        "bodyMatch": {
+          "Name": "m80-conf-connector"
+        }
+      },
+      "capture": {
+        "connectorId": "Id"
+      }
     },
     {
       "name": "get-until-active",
       "operation": "GetNetworkConnector",
       "method": "GET",
       "path": "/2026-04-04/network-connectors/${connectorId}",
-      "expect": { "status": 200 },
-      "until": { "path": "State", "equals": "ACTIVE", "timeoutSec": 900, "intervalSec": 5 }
+      "expect": {
+        "status": 200
+      },
+      "until": {
+        "path": "State",
+        "equals": "ACTIVE",
+        "timeoutSec": 900,
+        "intervalSec": 5
+      }
     },
     {
       "name": "list",
       "operation": "ListNetworkConnectors",
       "method": "GET",
       "path": "/2026-04-04/network-connectors",
-      "expect": { "status": 200 }
+      "expect": {
+        "status": 200
+      }
     },
     {
       "name": "update",
@@ -46,19 +69,27 @@
       "body": {
         "Configuration": {
           "VpcEgressConfiguration": {
-            "SubnetIds": ["${subnetId}"],
-            "SecurityGroupIds": ["${securityGroupId}"]
+            "SubnetIds": [
+              "${subnetId}"
+            ],
+            "SecurityGroupIds": [
+              "${securityGroupId}"
+            ]
           }
         }
       },
-      "expect": { "status": 202 }
+      "expect": {
+        "status": 202
+      }
     },
     {
       "name": "delete",
       "operation": "DeleteNetworkConnector",
       "method": "DELETE",
       "path": "/2026-04-04/network-connectors/${connectorId}",
-      "expect": { "status": 202 }
+      "expect": {
+        "status": 202
+      }
     }
   ]
 }

docs/floci.md

@@ -1,5 +1,17 @@
 # Division of labor with floci
 
+## Architecture findings (2026-07-29)
+
+Research against the local floci fork, recorded so the implementation issues stand alone.
+
+Floci is Quarkus. Services are JAX-RS controllers registered in `ResolvedServiceCatalog` as descriptors that claim requests by sigv4 signing name; rest-json dispatch then falls to JAX-RS path matching. Both MicroVM services sign as `lambda`, so their requests arrive under floci's lambda claim and route purely by path, and the MicroVM URI families (`/2025-09-09/`, `/2026-04-04/`, plus tags at `/2017-03-31/tags/`) collide with nothing the existing `LambdaController` serves. The bedrock-agentcore branch in the fork is the recipe for the whole shape: controllers, service, model classes, catalog descriptor, config toggle, tests, in reviewable conventional commits.
+
+CloudFormation provisioning has two plug points. The legacy path is a switch in `CloudFormationResourceProvisioner` calling services in-process. The newer path is the `CfnResourceProvisioner` interface with `CloudFormationResourceRegistry` (`SqsCfnProvisioner` is the model). New resource types go in the new way.
+
+Scope correction to the split below: chant's `MicrovmApp` emits `AWS::Lambda::NetworkConnector` when VPC egress is requested, so the CFN-sufficient subset includes connectors, not just `MicrovmImage`. The conformance suite's `subset:floci` tag covers connectors accordingly.
+
+Delivery constraints. Nothing is pushed to the fork or upstream until the work is complete and green locally. Upstream delivery follows the fork's established convention: a `[FEAT]` issue (Service / API Action / AWS documentation / why / willing-to-PR template) filed together with its PR, one pair per reviewable unit. Conventional commits throughout. The fork-only `publish-docker.yml` (manual dispatch, any ref, multi-arch to GHCR) publishes a testing image at delivery time, not before.
+
 ## The split
 
 | Concern | Home | Why |
@@ -12,7 +24,7 @@ floci upstream is `floci-io/floci`, Java, in-tree service modules, 18k stars, no
 
 ## Asymmetric scope
 
-The floci module implements the subset CFN provisioning needs. Image create, get, delete, build lifecycle enough for stack create and delete to converge, basic VM CRUD if `AWS::Lambda::Microvm` ever becomes a CFN type. It does not need tokens, endpoint stubs, idle timers, or drift levers. Scoping it narrow keeps the second implementation cheap and the drift surface small.
+The floci module implements the subset CFN provisioning needs. Image create, get, delete, build lifecycle enough for stack create and delete to converge, network connectors (`MicrovmApp` emits `AWS::Lambda::NetworkConnector`), and basic VM CRUD only if `AWS::Lambda::Microvm` ever becomes a CFN type. It does not need tokens, endpoint stubs, idle timers, or drift levers. Scoping it narrow keeps the second implementation cheap and the drift surface small.
 
 ## Sequencing