yvgude--lean-ctx/docs/specs/context-package-v1.md

Context Package Specification v1

Status: Draft
Schema Version: 1
Format: .ctxpkg (JSON)
Max File Size: 10 MB
License: CC BY 4.0

Overview

A .ctxpkg file is a single JSON document that packages AI-agent context into a portable, versioned, and verifiable format. It consists of a manifest (metadata + integrity) and a content section (typed layers).

File Structure

{
  "manifest": { ... },
  "content": { ... }
}

The top-level object has exactly two keys: manifest and content.

Manifest

Field	Type	Required	Description
schema_version	u32	Yes	Must be 1
name	string	Yes	Package name. Pattern: [a-zA-Z0-9._-], max 128 chars
version	string	Yes	Package version. Pattern: [a-zA-Z0-9._+-], max 64 chars, must not start with .
description	string	Yes	Human-readable description
author	string	No	Package author
created_at	string (ISO 8601)	Yes	Creation timestamp
updated_at	string (ISO 8601)	No	Last update timestamp
layers	array<LayerType>	Yes	Non-empty, no duplicates
dependencies	array<Dependency>	No	Package dependencies (default: [])
tags	array<string>	No	Searchable tags (default: [])
integrity	Integrity	Yes	Hash verification data
provenance	Provenance	Yes	Origin tracking
compatibility	Compatibility	No	Tool/language requirements
stats	Stats	No	Content statistics

LayerType

One of: "knowledge", "graph", "session", "patterns", "gotchas"

Dependency

Field	Type	Required	Description
name	string	Yes	Dependency package name
version_req	string	Yes	Version requirement
optional	bool	No	Whether the dependency is optional (default: false)

Integrity

Field	Type	Required	Description
sha256	string	Yes	64-char lowercase hex. Composite hash: SHA-256("{name}:{version}:{content_hash}")
content_hash	string	Yes	64-char lowercase hex. SHA-256(canonical_json(content))
byte_size	u64	Yes	Byte length of JSON.stringify(content). Must be > 0

Integrity Verification Algorithm

1. Serialize the content object to canonical JSON (keys sorted, no extra whitespace).
2. Compute SHA-256 of the serialized content bytes. Compare with content_hash.
3. Compute SHA-256("{name}:{version}:{content_hash}"). Compare with sha256.
4. Verify byte_size matches the serialized content length.
5. If any check fails, reject the package.

Provenance

Field	Type	Required	Description
tool	string	Yes	Tool that created the package (e.g., "lean-ctx")
tool_version	string	Yes	Version of the creating tool
project_hash	string	No	Hash of the source project at creation time
source_session_id	string	No	Session ID during creation

Compatibility

Field	Type	Required	Description
min_lean_ctx_version	string	No	Minimum tool version required to load
target_languages	array<string>	No	Target programming languages
target_frameworks	array<string>	No	Target frameworks

Stats

Field	Type	Description
knowledge_facts	u32	Number of knowledge facts
graph_nodes	u32	Number of graph nodes
graph_edges	u32	Number of graph edges
pattern_count	u32	Number of patterns
gotcha_count	u32	Number of gotchas
compression_ratio	f64	Estimated compression ratio

Content Layers

The content object contains one key per declared layer. Only layers listed in manifest.layers should be present.

knowledge

Field	Type	Description
facts	array<KnowledgeFact>	Structured knowledge entries
patterns	array<ProjectPattern>	Recurring code/architecture patterns
insights	array<ConsolidatedInsight>	Higher-level insights derived from facts
exported_at	string (ISO 8601)	Export timestamp

KnowledgeFact

Field	Type	Description
category	string	Fact category (e.g., "architecture", "convention")
key	string	Fact identifier
value	string	Fact content
confidence	f32	Confidence score (0.0 - 1.0)
source	string	Where the fact was learned
imported_from	string (optional)	Package name if imported

graph

Field	Type	Description
nodes	array<GraphNode>	Code entities
edges	array<GraphEdge>	Relationships between entities
exported_at	string (ISO 8601)	Export timestamp

GraphNode

Field	Type	Description
kind	string	Node type (e.g., "function", "class", "module")
name	string	Entity name
file_path	string	Source file path
line_start	u32 (optional)	Start line
line_end	u32 (optional)	End line
metadata	string (optional)	Additional context

GraphEdge

Field	Type	Description
source_path	string	Source file path
source_name	string	Source entity name
target_path	string	Target file path
target_name	string	Target entity name
kind	string	Edge type (e.g., "calls", "imports", "inherits")
metadata	string (optional)	Additional context

session

Field	Type	Description
task_description	string (optional)	What the session was about
findings	array<Finding>	Discoveries during the session
decisions	array<Decision>	Decisions made
next_steps	array<string>	Planned follow-up actions
files_touched	array<string>	Files modified during the session
exported_at	string (ISO 8601)	Export timestamp

Finding

Field	Type	Description
summary	string	Finding description
file	string (optional)	Related file
line	u32 (optional)	Related line number

Decision

Field	Type	Description
summary	string	Decision description
rationale	string (optional)	Why this decision was made

patterns

Field	Type	Description
patterns	array<ProjectPattern>	Standalone pattern definitions
exported_at	string (ISO 8601)	Export timestamp

gotchas

Field	Type	Description
gotchas	array<Gotcha>	Known pitfalls
exported_at	string (ISO 8601)	Export timestamp

Gotcha

Field	Type	Description
id	string	Unique identifier
category	string	Gotcha category
severity	string	Severity level (e.g., "high", "medium", "low")
trigger	string	What triggers this gotcha
resolution	string	How to resolve it
file_patterns	array<string>	Glob patterns for affected files
confidence	f32	Confidence score (0.0 - 1.0)

Transport Envelope

For agent-to-agent transfer, packages can be wrapped in a TransportEnvelopeV1:

Field	Type	Description
format_version	u32	Must be 1
sender	AgentIdentity	Sender agent identity
recipient	AgentIdentity (optional)	Intended recipient
content_type	string	Must be "context_package" for .ctxpkg payloads
payload_json	string	JSON-serialized package content
signature	string (optional)	HMAC-SHA256 signature
metadata	object (optional)	Additional transport metadata

Signature Algorithm

When signature is present, it is computed as:

HMAC-SHA256(key=secret, message="v2:{content_type}:{payload_json}")

The signature is hex-encoded. Verification uses constant-time comparison.

Validation Rules

1. schema_version must equal 1.
2. name must be non-empty, max 128 chars, matching [a-zA-Z0-9._-]+.
3. version must be non-empty, max 64 chars, matching [a-zA-Z0-9._+-]+, not starting with ..
4. layers must be non-empty with no duplicates.
5. integrity.sha256 and integrity.content_hash must be 64-char lowercase hex strings.
6. integrity.byte_size must be greater than 0.
7. File size must not exceed 10 MB.
8. Transport envelope payload must not exceed 2 MB.

Legacy Compatibility

Files with the .lctxpkg extension (used before v3.6.14) are accepted for import with the same schema.

Reference Implementation

The reference implementation is LeanCTX. Source code: github.com/yvgude/lean-ctx.