Skip to content

Source Manifest

The handbook is generated and reviewed against the local Solidity snapshot at:

/Users/marcos/Desktop/centurion_phase1_upgradeable_refactor

The lock file is:

source-manifest.lock.json

What The Lock Proves

The manifest records every Solidity file inspected by tools/extract_solidity_inventory.py. For each file it includes the absolute source path, source-root-relative path, SHA-256 hash, file size, modified time, detected contracts/interfaces/libraries, public constants, state variables, modifiers, external/public functions, privileged-function candidates, events, errors, implementation metadata labels, generation timestamp, generator version, and source git commit hash when available.

In the current local source directory, no git repository metadata is available. The manifest therefore records Evidence required for the source git root and commit. That is an evidence gap, not a pass condition. A production handbook package should either point at a committed Solidity repository or include an independently archived source bundle with a digest.

Source-Grounded Claims

Claims about contract behavior are source-grounded only when they trace to:

  • the current Solidity files under the source root;
  • the generated inventory at docs/appendices/generated-solidity-inventory.md;
  • the source manifest lock JSON; or
  • an explicitly inspected contract line, function, event, state variable, or error.

Evidence outside the local snapshot, such as deployed addresses, verified explorer source, multisig owners, offchain oracle feeds, Foundry results, audit reports, or governance approvals, must not be claimed as complete unless that evidence has been separately inspected. Use Evidence required where the source alone cannot prove the claim.

Regeneration Procedure

Run:

bash python3 tools/extract_solidity_inventory.py

or:

bash make inventory

This rewrites both:

  • docs/appendices/generated-solidity-inventory.md
  • docs/appendices/source-manifest.lock.json

After regenerating, review the git diff locally, then update human-written pages that depend on changed functions, state variables, events, errors, metadata constants, or privilege surfaces.

Drift Detection

Documentation drift exists when any of these are true:

  • a Solidity file hash in the manifest no longer matches the local source;
  • a Solidity file appears under the source root but not in the manifest;
  • a public or privileged function appears in the generated inventory but is absent from the permission matrix without an intentional-exclusion note;
  • a page describes a removed switch or control as current behavior;
  • a page claims a pass, approval, deployment state, or verification result without current evidence.

tools/audit_handbook_quality.py checks these conditions that can be verified locally. It does not replace source review, security review, or deployed-state verification.

When Solidity Changes

When the Solidity snapshot changes, the required sequence is:

  1. Regenerate the inventory and manifest.
  2. Reconcile DepositContractCTN permissioning, custody/readiness, upgrade-governance, and economic/claim-safety descriptions.
  3. Reconcile the permission matrix against privileged-function candidates.
  4. Update runbooks and state machines affected by new or removed functions, events, or errors.
  5. Run the quality audit and strict MkDocs build.
  6. Commit the synchronized docs and generated source-traceability files together.