Turn OpenAPI into a Reviewable Connector Draft

Day 01 located connector control between the caller and runtime. An OpenAPI Description is a machine-readable contract for an HTTP API, but parsing it does not prove that every reference resolves or every operation is safe to expose. Today you will validate a supplied OpenAPI 3.1.2 document, translate one operation into a neutral REST tool draft, and produce SCG-R02 without executing it.

OpenAPI defines the shape of paths, operations, parameters, and schemas; it does not grant network or data authority. The normative format is the OpenAPI Specification 3.1.2. This lab adds a stricter import policy: external references are rejected until an operator explicitly approves and snapshots them.

The spec store owns the immutable input bytes and checksum. Connector control parses those bytes with resource limits, rejects reference cycles and unresolved references, and requires a unique operationId. The example below is deliberately small enough to inspect.

openapi: 3.1.2
info:
  title: Atlas Calendar Lab
  version: 1.0.0
paths:
  /v1/events/{eventId}:
    get:
      operationId: getEvent
      parameters:
        - in: path
          name: eventId
          required: true
          schema: { type: string, minLength: 1 }
      responses:
        "200": { description: Event found }

{
  "checks": ["parse", "reference-budget", "unique-operation-id", "input-schema"],
  "externalReferences": "deny-until-approved",
  "maxDocumentBytes": 262144
}

A dangling $ref, duplicate operationId, or document above the byte budget blocks the draft. A missing description produces a warning because it harms review quality without changing the request schema.

Translation creates a draft, not a live tool. The config store records the source checksum, selected operation, input mapping, unresolved warnings, and review state. Only an explicit commit changes the active draft version.

{
  "draftId": "calendar-lab:getEvent:v1",
  "sourceSha256": "8f4e3c3f0a7b6d9e2c1a5f8b7d4e6c9a0b2d3f5e7a9c1b4d6e8f0a2c4b6d8e0f",
  "method": "GET",
  "pathTemplate": "/v1/events/{eventId}",
  "inputSchema": { "eventId": { "type": "string", "minLength": 1 } },
  "state": "review-required"
}

{
  "receipt": "SCG-R02",
  "acceptedOperations": 1,
  "blockedOperations": 0,
  "warnings": [],
  "executedRequests": 0
}

The normal path yields one reviewable draft. The denied path replaces the schema with an unresolved external reference and must yield zero committed tools. Recovery restores the pinned local schema and reruns validation. The unaffected control proves the Day 01 public route still works. Cleanup removes draft versions created by the exercise while retaining the input checksum in the evidence receipt.

Given a supplied violation and policy table, decide only block or warn. An unresolved external reference is block; a missing non-semantic description is warn. The scored result is one word plus the matching policy identifier, so unknown_count=1 and evaluation is deterministic.

The misconception is “valid YAML means safe connector.” Replay the parser with a syntactically valid dangling reference to contrast syntax with a resolved execution contract. Decline free-form API redesign, scope selection, or runtime code generation because each introduces extra unknowns.

SCG-R02 is the committed draft ID, source checksum, deterministic violation list, and proof of zero execution. Day 03 consumes the draft's protected resource URL and treats every discovered authorization URL as new untrusted input.