Output Locations

Generated paths

TypeScript target

A TypeScript spec is a private static input. Jaunt writes the declaration mirror, implementation, and sidecar under the configured generated directory; production code imports the committed facade next to the spec:

src/slug/
  index.jaunt.ts
  index.context.ts
  index.ts
  __generated__/
    index.api.ts
    index.ts
    index.jaunt.json

The generated implementation and mirror carry jaunt:module, structural, prose, and API digests. The sidecar records the same contract identity plus exact artifact hashes. jaunt sync re-renders the deterministic mirror and its sidecar bookkeeping, but it does not rewrite a built body, replace an existing facade, or advance the built implementation's provenance to a changed contract. Semantic and fingerprint re-stamps happen during jaunt build; compatible alpha-format repairs happen through jaunt migrate --language ts. Do not edit any of the three machine-owned files by hand.

Python target

For a spec module inside a package, the generated code lands in a __generated__/ dir beside the source, keeping the package structure:

A top-level spec module — a bare module directly under a source root, not inside a package — maps to a single top-level __generated__/ dir:

Package-nested __generated__/ dirs get an __init__.py. The single top-level __generated__/ dir is deliberately left without one, so it resolves as a PEP 420 namespace package: two installed distributions that each ship a top-level __generated__ merge instead of shadowing each other.

Provenance header

Every generated file opens with a comment header. A build module looks like:

# This file was generated by jaunt. DO NOT EDIT.
# jaunt:tool_version=1.3.0
# jaunt:kind=build
# jaunt:source_module=demo.specs
# jaunt:module_digest=sha256:9c39cc26…f656d76a
# jaunt:digest_scheme=2
# jaunt:spec_digests={"demo.specs:add": {"p": "fd2f90c7…", "s": "bb83f44e…"}}
# jaunt:generation_fingerprint=sha256:1572e3c8…c33b42692
# jaunt:module_api_digest=sha256:4fe71801…afbb1b681
# jaunt:module_context_digest=sha256:1f77c98f…54b861dc
# jaunt:spec_refs=["demo.specs:add"]

Jaunt reads these fields to decide whether a module is stale:

• module_digest covers the module's own spec inputs (signatures, docstring contracts, decorator kwargs, transitive deps).
• module_api_digest covers the exported dependency contract a downstream module sees: callable signatures, the full cleaned docstring, and for whole-class specs the declared members and method signatures. An upstream API change can therefore stale a downstream module whose own source never changed.
• module_context_digest and generation_fingerprint cover the prompt context and engine/prompt fingerprint that produced the file.

kind is build or test. For test modules the header is otherwise the same shape.

.pyi stubs

With [build] emit_stubs = true (the default), a successful build also writes a provenance-headed .pyi beside each spec module, so type checkers and editors see real signatures. Docstring-only @jaunt.magic classes expose their designed __init__/methods; decorated spec functions appear undecorated with their exact signatures.

# This .pyi stub was generated by jaunt. DO NOT EDIT.
# jaunt:tool_version=1.3.0
# jaunt:kind=stub
# jaunt:source_module=demo.specs
# jaunt:generated_digest=sha256:46ae3973…c4a9331b
# jaunt:inputs_digest=sha256:4a7f40a9…ddb7fa69

from __future__ import annotations


import jaunt


def add(a: int, b: int) -> int:
    ...

A missing or stale stub marks its module stale for jaunt status and jaunt check. A hand-authored .pyi (one without the jaunt header) is never overwritten — it is skipped with a warning.

What clean removes

For Python, jaunt clean removes __generated__/ directories under the configured source and test roots, plus header-marked .pyi stubs. It never touches a hand-authored .pyi. Preview with jaunt clean --dry-run, which lists exactly what would go:

"would_remove": [
  "/path/to/src/demo/__generated__",
  "/path/to/src/demo/specs.pyi"
]

For TypeScript, clean works from the worker's artifact manifest instead of deleting an arbitrary directory. It removes Jaunt-owned implementations, API mirrors, freshness sidecars, and generated magic-test batteries. It preserves *.jaunt.ts[x] inputs, handwritten context, public facades, and committed contract batteries.

Next: Limitations.