🔒 Deterministic Build Lockfile

Intend uses a lockfile system (intend.lock) to ensure that your generated code is stable, reproducible, and fast.

Why a Lockfile?

Generative AI is inherently probabilistic. If you ask an LLM to "Generate a function to add two numbers" twice, it might give you slightly different code (different variable names, different formatting) even if the logic is the same.

In a professional software environment, this variability is dangerous. You want to know exactly what code is being deployed, and you want your teammates to be running the same code as you.

The intend.lock file solves this by:

1. Pinning implementations: Once a piece of code is generated and validated, it is stored in the lockfile.
2. Eliminating drift: Your code won't change unless you intentionally change the .intent file or your configuration.
3. Speeding up builds: Unchanged intents are pulled instantly from the lockfile, bypassing the AI completely.

How it Works

When you run intend build, the compiler performs these steps for each intent:

1. Hashing: It creates a hash based on the .intent source code and your intend.config.json (specifically the provider and model settings).
2. Lookup: It checks intend.lock for an entry matching that file path and hash.
3. Recovery: If a match is found, the cached TypeScript code is restored immediately.
4. Generation: If no match is found (or if you use the --force flag), the AI generates new code, which is then validated and saved back into the lockfile.

Committing to Version Control

Super Important: Always commit your intend.lock file to Git.

Just like package-lock.json in npm or bun.lock in Bun, the intend.lock file is a critical part of your source of truth. By committing it:

• Your CI/CD pipeline will use the exact same code you generated locally.
• Your teammates won't get different results when they run build.
• You can review changes to the generated code during Pull Requests.

Forcing a Rebuild

If you want to re-generate your code (perhaps to use a newer model or a different prompt context), you can bypass the lockfile:

# Re-generate everything
intend build --force

# Or delete the lockfile manually
rm intend.lock

Structure of intend.lock

The lockfile is a JSON file that looks something like this:

{
  "version": "1.0",
  "files": {
    "src/intents/user_service.intent": {
      "sourceHash": "a1b2c3d4...",
      "configHash": "f5e6d7c8...",
      "generatedCode": "export async function CreateUser(...) { ... }",
      "model": "gemini-2.0-flash",
      "provider": "gemini",
      "timestamp": 1706421541000
    }
  }
}