---
title: Two-Pass Contract Compilation
url: https://www.emergentmind.com/topics/two-pass-contract-compilation
type: topic
---

# Two-Pass Contract Compilation

Searching arXiv for the specified paper to ground the article.
Two-pass contract compilation is a contract-construction procedure within a meta-engineering harness for AI-native software production. In the formulation reported in "Meta-Engineering Harnesses for AI-Native Software Production: A Contract-Driven Adversarial Verification Architecture with Early Deployment Report" [2605.25665], the procedure splits specification work into a first pass that expands a raw feature request into a structured contract skeleton and a second pass that prunes unsupported clauses while eliminating ambiguity. The resulting contract is then frozen as the single source of truth for implementation, adversarial testing, reviewer-based inspection, failure arbitration, and outer-loop calibration. Within that architecture, two-pass compilation is presented not as a prompt-engineering convenience but as the mechanism by which operational and product feature requirements become explicit, machine-checkable, and auditable over repeated production cycles.

## 1. Conceptual role and motivation

Two-pass contract compilation is motivated by two broad risks that arise when an AI agent is given a free-form issue description such as "Add in-app payments backed by Stripe." The first is under-specification: omission of key edge cases, state transitions, error conditions, or trust boundaries that the business requires. The second is over-specification: invention of behavior or constraints not supported by the customer. The architecture addresses both risks by separating contract construction into a "Completeness pass" and a "Scope & Ambiguity pass" [2605.25665].

The first pass turns the raw issue and any domain specializations into a structured draft that makes previously implicit assumptions explicit, including HTTP methods, URL patterns, request/response schemas, data invariants, error codes, and authentication rules. The stated purpose is to prevent the builder from "hallucinating" missing behavior. The second pass then removes unsupported clauses and rewrites vague language so that every requirement is implementable and unambiguous. Its stated purpose is to ensure that downstream agents do not lock in requirements that no stakeholder actually intended.

Taken together, the two passes improve contract completeness and verification-boundary clarity. The first guards against business-critical logic slipping through as "unwritten"; the second reduces the likelihood that test agents pursue invented edge cases. This suggests that the architecture treats specification quality as a first-order systems problem rather than as a by-product of code generation.

## 2. Formal contract model

The paper treats a contract $C$ as a tuple of named fields whose syntax can be expressed in JSON or markdown and whose semantics follow a simple type-and-state model:

$$
C = \langle module, version, apiSpec, invariants, gaps \rangle
$$

Here, $module \in String$ names the logical component, such as "NGPayments"; $version \in String$ records the contract version; $apiSpec \in ApiSpec$ captures the API description; $invariants \in \mathcal{P}(Inv)$ is a set of boolean properties that must hold before or after each operation; and $gaps \in \mathcal{P}(String)$ logs known omissions for calibration [2605.25665].

The API substructure is defined as

$$
ApiSpec = \langle basePath: String;\ auth: AuthRule;\ endpoints: [Endpoint] \rangle
$$

and each endpoint is defined as

$$
Endpoint = \langle method: \{GET|POST|PUT|DELETE\};\ path: String;\ inputs: Schema\ (\text{optional});\ outputs: Schema;\ sideEffects: [Effect];\ errors: [ErrorCode];\ preconditions: [Pred];\ postconditions: [Pred] \rangle
$$

where $Pred$ is a Boolean predicate over inputs, outputs, and mutable state.

The paper gives an example invariant in operational form:

$$
\forall invoiceId, amount:\ \text{after POST } /payments/intent/:invoiceId,\ invoice.amount\_cents = quote\_data.total\_cents.
$$

It also provides a redacted pseudo-JSON instance with `"module": "NGPayments"`, `"version": "1.0.0"`, an API rooted at `"/ng/payments"`, the authentication rule `"Supabase Bearer token; JWT identity authoritative"`, and a field for `"known_gap_identified_after_deployment"` [2605.25665].

This formalization is significant because it binds feature intent to explicit state transitions, schemas, and invariants rather than leaving them embedded in natural-language issue descriptions. A plausible implication is that the contract is meant to function as a typed coordination object across generation, testing, and review.

## 3. Pass 1: completeness-oriented skeleton generation

The first pass, labeled the "Completeness pass," consumes three classes of input: `rawIssue`, `specializationRecord` (optional), and `memoryContext`. The raw issue is a free-form feature description or GitHub issue. The specialization record supplies domain hints such as "In payments, always require idempotency keys," "All money fields are in cents," and "Stripe state machine must be mirrored in our DB." The memory context carries past decisions and existing API patterns [2605.25665].

The transformation described in pseudocode constructs a skeleton by extracting a module name, bumping the module version, inferring a base path and authentication rule, and iterating over issue sentences that match an endpoint pattern. For each such sentence, the pass extracts or infers the HTTP method, path, input schema, output schema, side effects, error codes, preconditions, and postconditions. It also infers invariants from the raw issue and the specialization record.

The example skeleton fragment for `NGPayments` illustrates the level of explicitness expected after pass 1. It includes a base path of `/ng/payments`, the authentication rule `Supabase Bearer token; JWT subject → user_id`, and endpoints such as `POST /intent/:invoiceId` and `POST /confirm/:invoiceId`. The `POST /intent/:invoiceId` endpoint is specified with inputs `{ invoiceId: uuid }`, a return payload `{ client_secret, payment_intent_id, payment_type, amount_cents }`, side effects including `Invoice.payment_status ← "processing"` and persistence of `payment_intent_id`, and errors `403, 404, 409, 422, 502`. The `POST /confirm/:invoiceId` endpoint includes the precondition `Stripe PaymentIntent status == "succeeded"` and postconditions including `Invoice.payment_status ← "paid"`, `ServiceRequest.status ← "completed"`, `paid_at ← now()`, and clearing `payment_intent_id`. The listed invariants include `amount_cents = quote_data.total_cents`, `no platform fee`, `"paid" is terminal state`, and `Prevent duplicate intents` [2605.25665].

The significance of pass 1 lies in its systematic exposure of assumptions that would otherwise remain latent. In the paper's framing, this reduces the space in which builder agents can fill in missing behavior on their own.

## 4. Pass 2: scope pruning, ambiguity resolution, and refinement checks

After the skeleton is complete, a second agent takes it in isolation and applies two transformation classes. The first is scope pruning: for each clause in `skeleton.invariants` or each side effect in endpoints, unsupported clauses are removed if they are not stakeholder-supported. The second is ambiguity resolution: vague phrases such as "calculate amount" or "handle edge case" are rewritten into precise predicates, and if multiple readings are possible, the process queries the product reviewer or consults the specialization record [2605.25665].

The pseudocode for `compile_pass2` deep-copies the skeleton, iterates through invariants and endpoint clauses, removes clauses not supported by policy, and maps ambiguous preconditions and postconditions through disambiguation. The output is a refined contract in which side effects, preconditions, and postconditions have been filtered or sharpened.

Three verification checks are performed during refinement. Type-checking ensures that every input/output schema is a well-formed JSON-schema or OpenAPI type. Dependency analysis ensures that every state transition mentions only fields declared in the schema. Trust-boundary analysis ensures that no client-side mutable flag flows back without server-side authorization. The second pass can also tag certain invariants as "high risk," such as amount calculations, so that the test agent will focus adversarial effort on them. Once refined, the contract is frozen and published to two separate queues—one for the builder agent and one for the test agent—thereby guaranteeing structural independence [2605.25665].

A common misconception would be to treat the second pass as editorial cleanup. The architecture instead assigns it a verification function: it bounds the semantics that independent builders, testers, and reviewers are allowed to act upon. This suggests that ambiguity is handled as an operational defect, not merely a documentation defect.

## 5. Integration with adversarial and attention-based verification

Once pass 2 produces a finalized contract $C^\*$, it becomes the single source of truth for both verification regimes described in the architecture. Under independence-based verification, `BuilderAgent(C*)` produces implementation code, `TestAgent(C*)` produces an adversarial test suite, and a CI runner executes tests. Any failures are then routed into a four-way failure arbiter that distinguishes `Bug`, `SpecGap`, `Noise`, and `Ambiguity` [2605.25665].

The classifications are contract-relative. If an implemented behavior directly conflicts with a postcondition in $C^\*$, the case is classified as `Bug` and the implementation is fixed. If a failing test points at behavior not expressed in $C^\*$, the result is `Spec Gap`, and the contract is extended through a new mini two-pass cycle. If CI environment issues trigger failures, the case is `Noise`, leading to recalibration of the CI or test harness. If tests both pass and fail depending on interpretation, the case is `Ambiguity`, leading to contract-clause refinement and a restarted build/test cycle.

Attention-based verification operates in parallel through reviewer agents for product, security, architecture, and QA. Each consumes $C^\*$ together with code and tests and applies role-specific checklists, including checklists for UX, trust boundaries, and maintainability. Findings from these reviewers can back-propagate to the contract if they indicate residual ambiguity or missing edge cases.

The architectural significance is that contract compilation is not upstream documentation followed by downstream execution. It is the coordination layer through which implementation, adversarial testing, reviewer attention, and calibration are synchronized. A plausible implication is that the quality of $C^\*$ determines not only what is built but also what can be meaningfully verified.

## 6. Deployment evidence and the in-app payments case

The paper reports an early production deployment spanning 17 features over several weeks, with a detailed in-app payments case study used to expose limitations in contract completeness and verification boundaries. In that Stripe-backed feature, pass 1 produced a skeleton that captured creating `PaymentIntents`, confirming them, and updating invoice status. Pass 2 refined the phrase "derive amount from quote_data.total" into the invariant `amount_cents = quote_data.total_cents` [2605.25665].

On CI, the implementation passed all adversarial tests in two build-test cycles. Post-deployment, however, two `Spec Gap` failures were discovered. First, offline deposits were never deducted because the invariant set never mentioned stored, non-Stripe payments. Second, discount codes were not applied because no clause in $C^\*$ captured discount logic. The reported metrics from this case are: backend payment cycles to passing CI: `2`; known post-CI business-logic misses: `2 (Spec Gaps in contract completeness)`; time to contract refinement after gap discovery: `< 1 day`; and new specialization record entries spawned: `"invoice.deposits"` and `"invoice.discounts"` [2605.25665].

These failures drove two explicit harness improvements. The first was richer domain specializations for payments, specifically automatic injection of deposit and discount clauses in pass 1 when a payments feature is requested. The second was an expanded ambiguity checker in pass 2 that flags any monetary-field invariant lacking explicit listing of all contributing factors. The case therefore functions as evidence that passing adversarial tests in CI does not, by itself, establish contract completeness. In the terminology of the architecture, the decisive issue was not a detected implementation bug but incompleteness in the compiled specification.

## 7. Significance within AI-native software production

Within the broader meta-engineering harness, two-pass contract compilation is presented as a mechanism for transforming operational and product feature requirements into explicit contracts that can support continuous production, verification, deployment, maintenance, and adaptation across many operational contexts and long time horizons. The motivating application is CTO-as-a-service for small service firms, where the system manages websites, booking flows, payment systems, backoffice workflow automations, and AI-agent interfaces as continuously evolving technical infrastructure rather than one-off deliverables [2605.25665].

The reported architecture includes persistent markdown memory with specialization records, attention-based and independence-based verifications, a four-way failure arbiter, and outer-loop calibration. Two-pass contract compilation is described as lying at the heart of this architecture because it establishes the machine-checkable boundary around "what we intend to build." The paper's concluding characterization is that the approach sharpens that boundary so that no downstream agent can misread it, while all verification outcomes feed back into templates, specialization records, or review gates for future runs.

In this framing, the importance of two-pass compilation is not limited to improved specification hygiene. It anchors a continuously improving, auditable production process in which omissions can be classified, traced, and reincorporated into subsequent contract generation. This suggests a conception of AI-native software production in which reliability depends less on any single model and more on the disciplined compilation, verification, and calibration of contracts over time.

Source: https://www.emergentmind.com/topics/two-pass-contract-compilation