Seam

Accepted

A Seam is a specifically declared integration point in an Archetype where the Stitcher must generate custom code. Seams bound the Stitcher’s work: each Seam has an explicit contract — what to produce, where, using which Adapters, implementing what behaviors, and how the output will be verified.

Why Seams Exist

Without Seams, the Stitcher would have to discover where to write code by reading the entire scaffolded codebase, guessing at integration points, and producing whatever felt right. That approach produces unpredictable output and consumes tokens proportional to codebase size.

With Seams:

The Stitcher’s work is bounded by the Seam list — no exploration needed
Each Seam has a contract that defines success — verification can be mechanical
The Composer can pre-validate the Seam list before any LLM is invoked
Token consumption scales with the number and complexity of Seams, not with codebase size

This is the core mechanism that makes Almathal’s economics work.

What a Seam Declares

A Seam in an Archetype Spec contains:

seam_id — namespaced slug unique within the Archetype
type — typically code_generation; other types possible for non-code Seams (config generation, schema generation)
description — human-readable purpose
input — the data feeding into this Seam (often a Variation Point’s value)
output_files — exact path templates the Seam produces, each with:
- path_template — file path, possibly parameterized over inputs
- template_role — the role this file plays (list_view, form_view, service_layer, etc.)
- must_use_adapters — Adapters whose APIs must be used
- must_implement — behaviors the generated code must include
verification — how to confirm the Seam was filled correctly:
- compile — must the output compile?
- lint — must it pass linting?
- tests_must_pass — named test suites to run

A Worked Example

A Seam from a hypothetical internal-crud-admin Archetype:

{
  "seam_id": "seam:internal-crud-admin/entity-to-ui",
  "type": "code_generation",
  "description": "Generate React list and form views for each user-defined entity",
  "input": "variation.entities",
  "output_files": [
    {
      "path_template": "frontend/src/pages/{entity.name}List.tsx",
      "template_role": "list_view",
      "must_use_adapters": [
        "adapter:typescript/react",
        "adapter:typescript/tanstack-query",
        "adapter:typescript/shadcn"
      ],
      "must_implement": [
        "pagination",
        "filtering",
        "delete_action",
        "navigation_to_form"
      ]
    },
    {
      "path_template": "frontend/src/pages/{entity.name}Form.tsx",
      "template_role": "form_view",
      "must_use_adapters": [
        "adapter:typescript/react",
        "adapter:typescript/react-hook-form",
        "adapter:typescript/zod",
        "adapter:typescript/shadcn"
      ],
      "must_implement": [
        "validation",
        "submit_handler",
        "error_display",
        "navigation_back_to_list"
      ]
    }
  ],
  "verification": {
    "compile": true,
    "lint": true,
    "tests_must_pass": ["frontend/smoke_test_entity_pages"]
  }
}

When this Seam runs:

The Stitcher receives the Seam contract and the resolved entity definitions
For each entity, it generates two files: UserList.tsx and UserForm.tsx, ProductList.tsx and ProductForm.tsx, etc.
Each file uses the declared Adapters’ APIs (TanStack Query for data fetching, shadcn for UI primitives)
Each file implements the declared behaviors
The Build Validator compiles, lints, and runs the smoke test
If verification fails, the Stitcher gets the failure as context and retries

Seam Validation Before Stitching

Before the Stitcher is invoked, Seam Validation statically checks each Seam:

Does input reference an existing field in the Spec?
Are the must_use_adapters actually resolved into Slots?
Do those Adapters’ Manifests declare the necessary Capabilities?
Will any two Seams’ path_template outputs collide?
Does the Archetype’s scaffolding include the toolchain needed for verification?

A failure here means the Archetype definition is broken, not that the user did something wrong. The platform team fixes the Archetype.

Cross-Seam Coordination

Seams that produce coupled outputs (e.g., a backend API endpoint and a frontend client that calls it) need to agree on the contract between them. Two approaches:

Shared input. Both Seams take the same Variation Point or Spec field as input, ensuring they produce consistent output.
Sequential execution with handoff. Backend Seam runs first, producing an OpenAPI spec as a side-output. The frontend Seam’s input includes that OpenAPI spec, so the frontend client matches the backend.

Sequential execution with structured handoffs is the more robust pattern and is preferred where possible.

Verification Is Part of the Seam

Every Seam declares how its output will be verified. This is non-negotiable for production Archetypes. The verification fields tell the Build Validator:

What command to run (npm run typecheck, mvn compile, pytest tests/seam_x_test.py)
What success looks like (exit code 0, no error output)
What to do on failure (retry, hard-fail)

If a Seam cannot specify verification, that’s a signal the Seam itself is poorly defined. Vague Seams produce vague output.

Seams in Modules

Modules can also have internal Seams — places where the Module composes its constituent Adapters with specific integration code. These work the same way as Archetype Seams: declared, contracted, validated, filled by the Stitcher, verified.

Module Seams are typically filled once (when the Module is composed and admitted to the library) rather than per-generation, since the Module’s composition is fixed.

The Fallback Path Has No Seams

When the user’s request doesn’t match any Archetype and the system falls back to pure-LLM generation, there are no Seams. The Stitcher operates on the entire generation as one undifferentiated task. Token costs spike and trust guarantees do not apply. This is documented for the user at Build Approval.