Skip to main content

Module object

git_internal::internal

Module object 

Source
Expand description

Object model definitions for Git blobs, trees, commits, tags, and AI workflow objects.

This module is the storage-layer contract for git-internal. Git-native objects (Blob, Tree, Commit, Tag) model repository content, while the AI objects model immutable workflow history that Libra orchestrates on top.

§How Libra should use this module

Libra should treat every AI object here as an immutable record:

  • construct the object in memory,
  • populate optional fields before persistence,
  • persist it once,
  • derive current state later from object history plus Libra projections.

Libra should not store scheduler state, selected heads, active UI focus, or query caches in these objects. Those belong to Libra’s own runtime and index layer.

AI workflow objects are split into three layers:

  • Snapshot objects in git-internal answer “what was the stored fact at this revision?”
  • Event objects in git-internal answer “what happened later?”
  • Libra projections answer “what is the system’s current view?”

§Relationship Design Standard

Relationship fields follow a simple storage rule:

  • Store the canonical ownership edge on the child object when the relationship is a historical fact.
  • Low-frequency, strongly aggregated relationships that benefit from fast parent-to-children traversal may additionally keep a reverse convenience link.
  • High-frequency, high-cardinality, event-stream relationships should remain single-directional to avoid turning parent objects into rewrite hotspots.

§Three-Layer Design

+------------------------------------------------------------------+
| Libra projection / runtime                                       |
|------------------------------------------------------------------|
| thread heads / selected_plan_id / active_run / scheduler state   |
| live context window / UI focus / query indexes                   |
+--------------------------------+---------------------------------+
                                 |
                                 v
+------------------------------------------------------------------+
| git-internal event objects                                        |
|------------------------------------------------------------------|
| IntentEvent / TaskEvent / RunEvent / PlanStepEvent / RunUsage    |
| ToolInvocation / Evidence / Decision / ContextFrame              |
+--------------------------------+---------------------------------+
                                 |
                                 v
+------------------------------------------------------------------+
| git-internal snapshot objects                                     |
|------------------------------------------------------------------|
| Intent / Plan / Task / Run / PatchSet / ContextSnapshot          |
| Provenance                                                       |
+------------------------------------------------------------------+

§Main Object Relationships

Snapshot layer
==============

Intent --parents----------------------------> Intent
Intent --analysis_context_frames-----------> ContextFrame
Plan   --intent-----------------------------> Intent
Plan   --context_frames---------------------> ContextFrame
Plan   --parents----------------------------> Plan
Task   --intent?----------------------------> Intent
Task   --parent?----------------------------> Task
Task   --origin_step_id?-------------------> PlanStep.step_id
Run    --task-------------------------------> Task
Run    --plan?------------------------------> Plan
Run    --snapshot?--------------------------> ContextSnapshot
PatchSet   --run----------------------------> Run
Provenance --run_id-------------------------> Run

Event layer
===========

IntentEvent   --intent_id-------------------> Intent
IntentEvent   --next_intent_id?-------------> Intent
ContextFrame  --intent_id?------------------> Intent
TaskEvent     --task_id---------------------> Task
RunEvent      --run_id----------------------> Run
RunUsage      --run_id----------------------> Run
PlanStepEvent --plan_id + step_id + run_id-> Plan / Run / PlanStep
ToolInvocation--run_id----------------------> Run
Evidence      --run_id / patchset_id?-------> Run / PatchSet
Decision      --run_id / chosen_patchset_id?> Run / PatchSet
ContextFrame  --run_id? / plan_id? / step_id?> Run / Plan / PlanStep

§Libra read / write pattern

A typical Libra call flow looks like this:

  1. write snapshot objects when a new immutable revision is defined (Intent, Plan, Task, Run, PatchSet, ContextSnapshot, Provenance);
  2. append event objects as execution progresses (IntentEvent, TaskEvent, RunEvent, PlanStepEvent, RunUsage, ToolInvocation, Evidence, Decision, ContextFrame);
  3. rebuild current state in Libra from those immutable objects plus its own Thread, Scheduler, UI, and Query Index projections.

§Object Relationship Summary

FromFieldToCardinality
IntentparentsIntent0..N
Intentanalysis_context_framesContextFrame0..N
PlanintentIntent1 canonical
PlanparentsPlan0..N
Plancontext_framesContextFrame0..N
TaskparentTask0..1
TaskintentIntent0..1
Taskorigin_step_idPlanStep.step_id0..1
TaskdependenciesTask0..N
RuntaskTask1
RunplanPlan0..1
RunsnapshotContextSnapshot0..1
PatchSetrunRun1
Provenancerun_idRun1
IntentEventintent_idIntent1
IntentEventnext_intent_idIntent0..1 recommended follow-up
ContextFrameintent_idIntent0..1
TaskEventtask_idTask1
RunEventrun_idRun1
RunUsagerun_idRun1
PlanStepEventplan_idPlan1
PlanStepEventstep_idPlanStep.step_id1
PlanStepEventrun_idRun1
ToolInvocationrun_idRun1
Evidencerun_idRun1
Evidencepatchset_idPatchSet0..1
Decisionrun_idRun1
Decisionchosen_patchset_idPatchSet0..1
ContextFramerun_idRun0..1
ContextFrameplan_idPlan0..1
ContextFramestep_idPlanStep.step_id0..1

Modules§

blob
In Git, a blob (binary large object) is a type of Git object that stores the contents of a file. A blob object contains the binary data of a file, but does not contain any metadata such as the file name or permissions. The structure of a Git blob object is as follows:
commit
The Commit object is a data structure used to represent a specific version of a project’s files at a particular point in time. In Git, the commit object is a fundamental data structure that is used to track changes to a repository’s files over time. Whenever a developer makes changes to the files in a repository, they create a new commit object that records those changes.
context
AI Context Snapshot Definition
context_frame
Immutable context-frame event object.
decision
AI Decision Definition
evidence
AI Evidence Definition
integrity
Hash implementation for AI process objects.
intent
AI Intent snapshot.
intent_event
Intent lifecycle event.
note
Git Note object implementation
patchset
AI PatchSet snapshot.
plan
AI Plan snapshot.
plan_step_event
Plan-step execution event.
provenance
AI Provenance snapshot.
run
AI Run snapshot.
run_event
Run lifecycle event.
run_usage
Run usage / cost event.
signature
In a Git commit, the author signature contains the name, email address, timestamp, and timezone of the person who authored the commit. This information is stored in a specific format, which consists of the following fields:
tag
In Git objects there are two types of tags: Lightweight tags and annotated tags.
task
AI Task snapshot.
task_event
Task lifecycle event.
tool
AI Tool Invocation Definition
tree
In Git, a tree object is used to represent the state of a directory at a specific point in time. It stores information about the files and directories within that directory, including their names, permissions, and the IDs of the objects that represent their contents.
types
Object type, actor, artifact, and header primitives.
utils
Low-level helpers shared by object encode/decode routines: varint readers, type/size parsing, and thin zlib compression wrappers tuned for Git object formats.

Traits§

ObjectTrait
The Object Trait Defines the common interface for all Git object types, including blobs, trees, commits, and tags.