> ## Documentation Index
> Fetch the complete documentation index at: https://hyperlocalise.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Lockfile contract

> Understand what `.hyperlocalise.lock.json` stores, when to reset it, and why it is advisory.

## Canonical file name

The lockfile name is fixed to `.hyperlocalise.lock.json`.

`hyperlocalise` does not currently read `i18n.lock` or other alias names.

Keep the file in your project root so `run` and sync commands share the same checkpoint state.

The CLI writes the lockfile as **indented JSON** so diffs are readable. It keeps file size down by grouping task entries by target path and storing short field names.

## What the lockfile is for

Treat the lockfile as an **advisory checkpoint**, not your source of truth.

* Source of truth for translatable content is your source files.
* Source of truth for generated output is your target files.
* Source of truth for synced remote state is your TMS plus local artifacts.

The lockfile only records what the CLI already attempted or completed so it can skip repeated work.

It is not used to prove that a sync push is safe. Sync safety comes from current local files plus a fresh remote baseline read at execution time.

## Schema

Current shape:

```json theme={null}
{
  "adapter": "crowdin",
  "project_id": "12345",
  "last_pull_at": "2026-01-15T12:34:56Z",
  "locale_states": {
    "es-ES": {
      "revision": "rev_abc123",
      "updated_at": "2026-01-15T12:00:00Z"
    }
  },
  "run_completed": {
    "apps/web/lang/es-ES.json": {
      "checkout.submit": {
        "s": "7f4f7d...",
        "t": "1a2b3c..."
      }
    }
  }
}
```

Field meanings:

* `adapter`: active TMS adapter name.
* `project_id`: adapter-specific project identifier.
* `last_pull_at`: timestamp of the latest successful sync pull.
* `locale_states`: per-locale checkpoint map.
  * `revision`: adapter revision or cursor for incremental pull logic.
  * `updated_at`: last time that locale checkpoint was refreshed.
* `run_completed`: per-task completion map used by `run` for skip decisions. Current writes group entries by target path.
  * nested key: entry key inside the target file.
  * `s`: fingerprint of the source segment.
  * `t`: fingerprint of task dimensions, such as model, prompt, context fields, and related inputs.
* `active_run_id`: identifier for an in-progress run. It is cleared after a successful run.
* `run_checkpoint`: temporary per-task output checkpoint for interrupted runs. It is grouped by target path and cleared after a successful run.
  * `r`: run identifier.
  * `p`: source path.
  * `l`: target locale.
  * `v`: staged output value.
  * `s`, `t`, and `u`: source fingerprint, task fingerprint, and update timestamp.

New writes use a **32-character** lowercase hex prefix of SHA-512 for fingerprints. Older lockfiles may still store flat `target::entry` keys and full field names such as `source_hash` and `task_hash`. They may also store full **128-character** hex digests. The CLI accepts both shapes and both digest lengths.

## Lifecycle by command

### `hyperlocalise run`

* Reads `.hyperlocalise.lock.json` when planning tasks.
* Skips work already marked complete in `run_completed`.
* Persists successful tasks back to `run_completed`.

### `hyperlocalise sync pull`

* May read existing adapter and locale checkpoint metadata as a performance hint.
* Fetches a fresh remote snapshot for the requested scope.
* Updates `adapter`, `project_id`, `last_pull_at`, and `locale_states` after successful pull.

### `hyperlocalise sync push`

* May read adapter/project context from the lockfile.
* Does not require lockfile or sidecar metadata to authorize writes.
* Computes push diffs from local files plus a fresh remote baseline for the same scope.
* Does not replace source/target content authority.

## Safe reset guidance

Reset the lockfile when checkpoint state is stale or no longer trustworthy.

Common reset cases:

* you changed source text structure heavily
* you changed bucket mappings or file path templates
* you switched adapters or projects
* you suspect corrupted or manually edited checkpoint entries

Safe reset steps:

1. ensure your source and generated files are committed or backed up
2. delete `.hyperlocalise.lock.json`
3. run `hyperlocalise run --dry-run` to inspect the larger plan
4. run `hyperlocalise run` and/or `hyperlocalise sync pull` to rebuild checkpoint state

Expected side effects after reset:

* `run` may re-execute tasks that were previously skipped
* next sync pull may perform a broader refresh for locales
* CLI runtime can increase temporarily until checkpoints are rebuilt

## Team conventions

* Do not hand-edit lockfile fields unless debugging a local incident.
* Keep lockfile handling explicit in CI scripts.
* Review lockfile changes in pull requests when run/sync behavior looks unexpected.