Skip to main content

Module source_files

lifeloop

Module source_files 

Source
Expand description

Model instruction source-file rendering and managed-section apply.

Lifeloop owns one managed section inside each adapter’s instruction source file (AGENTS.md, CLAUDE.md, GEMINI.md, HERMES.md, OPENCLAW.md). The user owns the rest of the file. The managed section carries lifecycle integration metadata only — adapter id, integration mode, hook timing summary, host integration asset paths, template version, and one opaque client-supplied slot.

§Boundary (issue #16)

This module owns:

  • rendering managed-section bodies for each (adapter, integration mode) pair,
  • idempotent apply against an existing file body — create, update, no-op, stale-section replace,
  • fail-closed detection of malformed / multiply-managed / unbalanced marker pairs.

This module does not own:

  • filesystem IO. Callers handle reads, writes, and atomic replace. This module operates on &str / String exclusively.
  • client semantics. The client slot is an opaque String rendered verbatim; Lifeloop never parses it.
  • generated mirrors (e.g. CCD’s CLAUDE.md mirrored from AGENTS.md). That is a client concern.
  • host integration assets (.claude/settings.json, .codex/config.toml, etc.). Those live in crate::host_assets.

§Sentinel format

Managed sections are bracketed by stable markers:

<!-- LIFELOOP:BEGIN managed-section v=<N> adapter=<id> -->
...managed body...
<!-- LIFELOOP:END managed-section -->

See [docs/harness-concepts/source-files.md] for the boundary and decisions. The marker shape is part of the public source-file contract.

Structs§

ApplyResult
Result of apply: the new file body the caller should write, plus the outcome classification. body is None on ApplyOutcome::NoOp — the caller should skip the write entirely.
RenderedSourceFile
A rendered source file: the path hint Lifeloop owns, the managed section’s begin/end marker text, and the body Lifeloop would write inside the markers. Pure data — the caller decides how to write it.

Enums§

ApplyError
Errors apply returns when the existing file body is incompatible with the managed-section invariant. Apply never silently overwrites user-authored content.
ApplyOutcome
Outcome of apply. Exhaustive; callers match all variants for migration messaging.
SourceFileAdapter
Adapters Lifeloop ships source-file rendering for. Mirrors HostAdapter plus Gemini, which has a source file but no host integration assets in host_assets.rs today.

Constants§

TEMPLATE_VERSION
Current template version. Bumped when the body shape of the managed section changes in a way that requires stale-section replacement on existing repos. Independent of lifeloop.v0.x schema versions.

Functions§

apply
Apply rendered against existing (the current file body, or None if the file does not exist). Returns the new body to write and a classification of what changed.
render_for
Render the managed source file for adapter in integration_mode. client_slot is an opaque, optional client-supplied body. Lifeloop embeds it verbatim inside the managed section between <!-- CLIENT-SLOT:BEGIN --> and <!-- CLIENT-SLOT:END --> sub-markers. Lifeloop never parses or interprets the slot.