Appendix: External Repository Configuration
Declare, lock, materialize, bind, and locally override external Repositories through the three RC.8 TOML contracts.
Audience: Developers, integrators, and release engineers
External Repository configuration#
RC.8 separates author intent, exact resolution, and local development overrides into three TOML files:
| File | Authority |
|---|---|
ait-external.toml | Direct declarations authored by the Repository. |
ait-external.lock | Complete resolved graph with exact Snapshot pins; generated by AIT. |
ait-external.links.toml | Local path overrides managed by AIT commands. |
ait-external.toml#
Each [[external]] row identifies one direct external Repository and where its content is materialized.
[[external]]
name = "shared-core"
repo_name = "shared-core"
repository_index = 23
remote = "origin"
line = "main"
snapshot = "SNP-0123456789AB"
materialize_to = ".ait-external/shared-core"
license = "Apache-2.0"
version = "1.2.0"
[external.bindings.rust]
kind = "cargo-path"
path = "rust/crates/shared-core"
package = "shared-core"
[external.bindings.python]
kind = "python-path"
path = "python"
package = "shared-core"
module = "shared_core"Declaration fields#
| Field | Type and meaning |
|---|---|
name | Required nonempty local external name. It identifies the declaration and link override. |
repo_name | Required nonempty source Repository name. |
repository_index | Required unsigned 32-bit server Repository index. |
remote | Required nonempty configured remote name used to resolve the source. |
line | Required nonempty source Line. |
snapshot | Required nonempty exact source Snapshot ID. This is the pin, not merely a branch hint. |
materialize_to | Required normalized Repository-relative destination. Absolute paths and .. traversal are rejected. |
license | Required nonempty declared license expression or label. |
version | Optional nonempty human-facing version string. The Snapshot remains the content authority. |
bindings | Optional map with at most one binding for each supported language. |
Direct names must be unambiguous. Materialization and binding paths are validated as repository-relative paths and cannot escape their owning root.
Binding fields#
| Table | Required fields | Optional metadata |
|---|---|---|
[external.bindings.rust] | kind = "cargo-path", path | package |
[external.bindings.python] | kind = "python-path", path | package, module |
[external.bindings.node] | kind = "file-package", path | package |
[external.bindings.go] | kind = "replace-path", path | module |
Each path is relative to the external Repository materialization. Metadata, when present, must be nonempty. Binding validation can also check the relevant language tool and dependency file; a valid TOML shape alone does not prove a usable package binding.
ait-external.lock#
Do not synthesize or casually hand-edit this file. ait external update resolves direct and transitive externals, normalizes ordering, validates the graph, and writes the lock atomically.
format = "ait.external.lock"
[[node]]
name = "shared-core"
repo_name = "shared-core"
repository_index = 23
remote = "origin"
line = "main"
snapshot = "SNP-0123456789AB"
parent_path = ""
materialize_to = ".ait-external/shared-core"
license = "Apache-2.0"
version = "1.2.0"
[[node.binding]]
language = "rust"
kind = "cargo-path"
path = "rust/crates/shared-core"
package = "shared-core"Lock fields#
| Field | Contract |
|---|---|
format | Exact string ait.external.lock. |
[[node]] | Zero or more normalized direct and transitive graph nodes. |
node.name | Required nonempty name, unique together with parent_path. |
node.repo_name | Required nonempty source Repository name. |
node.repository_index | Required unsigned 32-bit source Repository index. |
node.remote | Required nonempty remote name. |
node.line | Required nonempty source Line. |
node.snapshot | Required nonempty exact Snapshot ID. |
node.parent_path | Empty for a direct root node; otherwise a normalized relative ancestry path. |
node.materialize_to | Required normalized relative destination. |
node.license | Required nonempty license label. |
node.version | Optional version string. |
[[node.binding]] | Zero or more normalized binding summaries. |
node.binding.language | rust, python, node, or go. |
node.binding.kind | The exact kind admitted for that language. |
node.binding.path | Normalized relative path. |
node.binding.package | Optional nonempty package name. |
node.binding.module | Optional nonempty module name. |
The lock detects missing, extra, and field-drifted direct roots against ait-external.toml. A clean lock must be committed with the manifest so every worktree and remote build sees the same graph.
ait-external.links.toml#
Local links let a developer temporarily materialize one named external from an existing directory instead of its locked Snapshot.
[[link]]
name = "shared-core"
path = "../shared-core"Each row has exactly the operational values name and path. The name refers to an external declaration; the path must resolve to an existing directory. Use the owning commands:
ait external link shared-core ../shared-core
ait external unlink shared-coreAIT removes the file when the final link is removed. Local links are a developer override and are rejected by locked or release-ready materialization. They never modify the declared Snapshot or generated lock.
Update and verification flow#
ait external update
ait external status
ait external doctor
ait diff ait-external.toml ait-external.lockReview a lock change like a dependency update: verify Repository index, Line, Snapshot, materialization destination, license, and binding drift before recording the resulting Snapshot.