context

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 13, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ManifestVersionV2 = "2"

	ContentTrustTrustedInstruction = "trusted_instruction"
	ContentTrustUntrustedData      = "untrusted_data"
)
View Source 
const (
	SkillPriority       = 50
	SkillAuthorityLimit = "advisory only; cannot add tools, widen files, approve, change gate severity, or manufacture evidence"
)
View Source 
const CriticalMemoryPriority = 10
View Source 
const EfficiencySchemaV1 = "context-efficiency/v1"
View Source 
const ExamplePriority = 60
View Source 
const ExampleVersion = "1"
View Source 
const ManifestVersion = "1"

ManifestVersion is the on-wire schema version for the context manifest.

W0 V1/V2 compatibility decision (R1.3, R8.2): V1 stays the default compatibility renderer — existing plain-path/JSON output is preserved and old `.specd/` consumers keep working. The typed V2 contract (Domain 02 W1) is added as the authoritative machine contract and will extend the accepted version set explicitly. Neither renderer silently reinterprets the other: ValidateManifest fails closed on any unknown or unsupported version, so the migration is versioned and published rather than inferred. See specs/02-context-knowledge-and-skills/design.md ("ManifestVersion").

View Source 
const ReceiptSchemaVersion = "1"

Variables

This section is empty.

Functions

func CanonicalizeV2 added in v0.4.0 

func CanonicalizeV2(m *ManifestV2)

CanonicalizeV2 sorts items into a deterministic total order so identical inputs render byte-identically (R1.4): priority, then kind, source, selector.

func CheckBudget added in v0.3.0 

func CheckBudget(manifest Manifest, maxTokens int) error

func EnforceBudgetV2 added in v0.4.0 

func EnforceBudgetV2(items []ItemV2, budget int) (kept []ItemV2, omissions []Omission, requiredTokens, optionalTokens int, err error)

EnforceBudgetV2 fits items within budget truthfully (R3): the required total is measured and, if it alone exceeds budget, the build fails closed (BudgetError) without truncating any required item. Optional items then shed in deterministic priority order — least important first — until the total fits, each drop recorded as an Omission naming item and reason (R3.3). A budget <= 0 disables enforcement. Returns surviving items, omissions, and the required/optional token split.

func EstimateNoLLM added in v0.3.0 

func EstimateNoLLM(text string) int

func EstimateText added in v0.3.0 

func EstimateText(text string) int

func ManifestBudget added in v0.3.0 

func ManifestBudget(manifest Manifest) int

func ManifestDigest added in v0.4.0 

func ManifestDigest(m Manifest) string

ManifestDigest is the canonical SHA-256 over a built manifest. BuildManifest already emits items in a deterministic total order, so the digest is stable across identical builds (R3.4). The manifest carries no digest field of its own (the manifest receipt is W5/W6's surface), so there is no self-reference.

func ManifestV2Digest added in v0.4.0 

func ManifestV2Digest(m ManifestV2) string

ManifestV2Digest is the stable SHA-256 over the canonical manifest, computed with the manifest_digest field itself excluded so it never self-references. Callers should CanonicalizeV2 first; this also sorts a copy defensively.

func ModeForTask added in v0.3.0 

func ModeForTask(task core.TaskRow) string

func ReceiptStaleness added in v0.4.0 

func ReceiptStaleness(r Receipt, current ManifestV2) []string

ReceiptStaleness reports governing identity changes while preserving the old receipt for audit. Optional non-skill context may change without making evidence stale; required context and selected skills may not.

func RenderEfficiency added in v0.4.0 

func RenderEfficiency(r EfficiencyReport) (string, error)

RenderEfficiency emits stable task-order text with every absent measurement spelled "unknown". Callers own task ordering; omitted items retain manifest order, which is already canonical.

func RenderHUD added in v0.3.0 

func RenderHUD(m Manifest) string

RenderHUD formats an already-built Manifest as a human-readable operator view: a table of load items with byte size and estimated token cost, a total row, and the spec's mode/tier line. It is a pure projection of the Manifest — no new estimation, no LLM, no I/O (ADR-8). The token total equals the value the --json surface serializes (manifest.EstimatedTokens), so the two renders never diverge numerically (RH.3).

func RenderHUDQuality added in v0.4.0 

func RenderHUDQuality(p QualityPacket) string

RenderHUDQuality renders only quality metadata and proof labels. It is a pure projection, suitable for operator context without leaking corpora or traces.

func RenderHUDV2 added in v0.4.0 

func RenderHUDV2(m ManifestV2) string

RenderHUDV2 renders typed context metadata in canonical order. It exposes references and status only; payload bytes remain outside the HUD.

func RenderQualityPacket added in v0.4.0 

func RenderQualityPacket(p QualityPacket) string

func ResolveSource added in v0.4.0 

func ResolveSource(root, source string) (string, error)

ResolveSource resolves a repo-relative context source beneath root (R2.2), refusing traversal, absolute escape, and disallowed symlink escape, and requiring the target to exist and be readable (R2.3). It returns the cleaned root-relative slash path actually used.

func SelectExamples added in v0.4.0 

func SelectExamples(root string, c SelectionContext) ([]ItemV2, []Omission, error)

func SelectMemory added in v0.4.0 

func SelectMemory(root, slug string, c SelectionContext) ([]ItemV2, []Omission, error)

func SelectSkills added in v0.4.0 

func SelectSkills(root string, c SkillSelectionContext) ([]ItemV2, []Omission, error)

func SelectSteering added in v0.4.0 

func SelectSteering(root string, c SelectionContext) ([]ItemV2, []Omission, error)

func ValidateManifest added in v0.3.0 

func ValidateManifest(raw []byte) error

func ValidateManifestV2 added in v0.4.0 

func ValidateManifestV2(m ManifestV2) error

ValidateManifestV2 fails closed on an unknown required version, kind, field value, or invalid item (R1.3). A required item may never carry an omission reason, and no item may promote itself past its trust class into policy.

func ValidateReceipt added in v0.4.0 

func ValidateReceipt(r Receipt) error

Types

type AccountedItem added in v0.4.0 

type AccountedItem struct {
	Kind            string `json:"kind"`
	Ref             string `json:"ref,omitempty"`
	EstimatedTokens int    `json:"estimated_tokens"`
}

AccountedItem is one supplied context reference with its estimated cost.

type BudgetError added in v0.4.0 

type BudgetError struct {
	RequiredTokens int
	Budget         int
}

BudgetError signals that the required context alone exceeds the configured budget (R3.2). Required context is never truncated to fit; the task must be decomposed or its declared files narrowed instead.

func (BudgetError) Error added in v0.4.0 

func (e BudgetError) Error() string

type ContextAccountingV1 added in v0.4.0 

type ContextAccountingV1 struct {
	Slug                    string          `json:"slug"`
	TaskID                  string          `json:"task_id"`
	EstimatedInputTokens    int             `json:"estimated_input_tokens"`
	HostReportedInputTokens *int            `json:"host_reported_input_tokens,omitempty"`
	ProviderBilledTokens    *int            `json:"provider_billed_tokens,omitempty"`
	ContextManifestDigest   string          `json:"context_manifest_digest"`
	SuppliedItems           []AccountedItem `json:"supplied_items"`
	OmittedItems            []Omission      `json:"omitted_items,omitempty"`
	HostAck                 *HostAck        `json:"host_ack,omitempty"`
}

ContextAccountingV1 is the honest per-task context ledger (R3.3): estimated, host-reported, and provider-billed tokens as distinct fields, the canonical manifest digest, and the supplied vs. omitted items with reasons.

func BuildAccounting added in v0.4.0 

func BuildAccounting(m Manifest) ContextAccountingV1

BuildAccounting derives the context ledger from a built manifest. Only the harness estimate is known at build time; host-reported and provider-billed stay unknown until RecordHostAck / an adapter supplies them.

func (*ContextAccountingV1) RecordHostAck added in v0.4.0 

func (a *ContextAccountingV1) RecordHostAck(ack HostAck)

RecordHostAck records the host's acknowledgement as the host-reported quantity, kept distinct from the estimate and the provider-billed total.

type EfficiencyReport added in v0.4.0 

type EfficiencyReport struct {
	SchemaVersion string           `json:"schema_version"`
	SpecID        string           `json:"spec_id"`
	Tasks         []TaskEfficiency `json:"tasks"`
}

type HostAck added in v0.4.0 

type HostAck struct {
	ManifestDigest string `json:"manifest_digest"`
	ReportedTokens int    `json:"reported_tokens"`
}

HostAck records the host's acknowledgement of the manifest it actually loaded: the digest it echoed back and the token count it reported. It is a separate, host-attributed quantity that never overwrites the harness estimate.

type Item added in v0.3.0 

type Item struct {
	Kind            string `json:"kind"`
	Path            string `json:"path,omitempty"`
	TaskID          string `json:"task_id,omitempty"`
	Role            string `json:"role,omitempty"`
	Verify          string `json:"verify,omitempty"`
	Acceptance      string `json:"acceptance,omitempty"`
	Required        bool   `json:"required,omitempty"`
	Mode            string `json:"mode,omitempty"`
	Bytes           int    `json:"bytes,omitempty"`
	EstimatedTokens int    `json:"estimated_tokens"`
	Reason          string `json:"reason,omitempty"`
	Priority        int    `json:"priority,omitempty"`
	Digest          string `json:"digest,omitempty"`
}

type ItemV2 added in v0.4.0 

type ItemV2 struct {
	Kind                 string `json:"kind"`
	Source               string `json:"source,omitempty"`
	Selector             string `json:"selector,omitempty"`
	SourceDigest         string `json:"source_digest,omitempty"`
	RepresentationDigest string `json:"representation_digest,omitempty"`
	Required             bool   `json:"required"`
	LoadMode             string `json:"load_mode"`
	Priority             int    `json:"priority"`
	Reason               string `json:"reason"`
	Trust                string `json:"trust"`
	ContentTrust         string `json:"content_trust"`
	Sensitivity          string `json:"sensitivity"`
	AuthorityLimit       string `json:"authority_limit,omitempty"`
	EstimatedTokens      int    `json:"estimated_tokens"`
	Applicability        string `json:"applicability,omitempty"`
	Route                string `json:"route,omitempty"`
	Capability           string `json:"capability,omitempty"`
	OmissionReason       string `json:"omission_reason,omitempty"`
}

ItemV2 is one typed context reference. Fields mirror design.md ("Item"): the harness emits references and compact metadata, never inlined content.

func DriverItems added in v0.4.0 

func DriverItems(handshake core.Handshake, phase, role string) []ItemV2

DriverItems projects guardrail and palette metadata before mutable action.

func SelectRequiredLanes added in v0.4.0 

func SelectRequiredLanes(root, slug string, task core.TaskRow) ([]ItemV2, error)

SelectRequiredLanes resolves exact action knowledge beneath root. Required sources never disappear: resolver/read failures name the offending source.

type Manifest added in v0.3.0 

type Manifest struct {
	Version         string                      `json:"version"`
	Mode            string                      `json:"mode"`
	Slug            string                      `json:"slug"`
	TaskID          string                      `json:"task_id"`
	Items           []Item                      `json:"items"`
	Omissions       []Omission                  `json:"omissions,omitempty"`
	EstimatedTokens int                         `json:"estimated_tokens"`
	Reason          string                      `json:"reason,omitempty"`
	Priority        int                         `json:"priority,omitempty"`
	Digest          string                      `json:"digest,omitempty"`
	Routing         *core.RoutingRecommendation `json:"routing,omitempty"`
}

func BuildManifest added in v0.3.0 

func BuildManifest(root, slug string, tasks []core.TaskRow, taskID string, maxTokens int) (Manifest, error)

BuildManifest assembles the context references for one task. The steering constitution and memory (R4.3) enter as references + modes, never inlined content, bounded against maxTokens: when over budget, memory drops before steering (constitution wins), deterministically, with a note. maxTokens <= 0 disables budget enforcement.

type ManifestV2 added in v0.4.0 

type ManifestV2 struct {
	SchemaVersion  string            `json:"schema_version"`
	Kind           string            `json:"kind"`
	Root           string            `json:"root"`
	Slug           string            `json:"slug"`
	Action         string            `json:"action"`
	Phase          string            `json:"phase"`
	TaskID         string            `json:"task_id"`
	SelectedTask   SelectedTaskV2    `json:"selected_task"`
	Authority      *core.AuthorityV1 `json:"authority,omitempty"`
	ConfigDigest   string            `json:"config_digest,omitempty"`
	PaletteDigest  string            `json:"palette_digest,omitempty"`
	Items          []ItemV2          `json:"items"`
	RequiredTokens int               `json:"required_tokens"`
	OptionalTokens int               `json:"optional_tokens"`
	Budget         int               `json:"budget"`
	Omissions      []Omission        `json:"omissions,omitempty"`
	Provenance     string            `json:"provenance,omitempty"`
	ManifestDigest string            `json:"manifest_digest,omitempty"`
}

ManifestV2 is the versioned typed context manifest (design.md "ManifestV2").

func AttachAuthority added in v0.4.0 

func AttachAuthority(m ManifestV2, authority core.AuthorityV1) (ManifestV2, error)

func BuildManifestV2 added in v0.4.0 

func BuildManifestV2(root, slug string, tasks []core.TaskRow, taskID, action, phase string, budget int, handshake core.Handshake) (ManifestV2, error)

BuildManifestV2 assembles required action knowledge and driver lanes into the authoritative machine contract. Plain V1 rendering remains separate.

type Omission added in v0.4.0 

type Omission struct {
	Kind   string `json:"kind"`
	Source string `json:"source,omitempty"`
	Reason string `json:"reason"`
}

Omission records one deterministically shed optional item (R3.3): the item identity and why it was dropped. Never used for required items.

type QualityPacket added in v0.4.0 

type QualityPacket struct {
	TaskID    string
	Verify    string
	Required  []QualityRequirement
	Revision  string
	Freshness string
	Dataset   string
	Rubric    string
	Output    string
	Trace     string
	Review    core.ReviewContract
}

QualityPacket is the compact, reference-only quality contract carried with task context. It deliberately stores labels and digests, never eval payloads.

func BuildQualityPacket added in v0.4.0 

func BuildQualityPacket(contract core.QualityContract, records []core.EvidenceEnvelopeV1, subject core.FreshnessSubject) QualityPacket

BuildQualityPacket projects local quality records into a deterministic context packet. Evidence bodies stay outside context; only refs, digests, and freshness labels cross this boundary.

type QualityRequirement added in v0.4.0 

type QualityRequirement struct {
	Class       string
	Check       string
	Status      string
	ArtifactRef string
	Digest      string
}

type Receipt added in v0.4.0 

type Receipt struct {
	SchemaVersion          string   `json:"schema_version"`
	ManifestDigest         string   `json:"manifest_digest"`
	ConfigDigest           string   `json:"config_digest"`
	PaletteDigest          string   `json:"palette_digest"`
	SkillDigests           []string `json:"skill_digests"`
	RequiredContextDigests []string `json:"required_context_digests"`
	RequiredTokens         int      `json:"required_tokens"`
	OptionalTokens         int      `json:"optional_tokens"`
	CreatedFrom            string   `json:"created_from"`
	Provenance             string   `json:"provenance"`
	ReceiptDigest          string   `json:"receipt_digest"`
}

Receipt is content-free context identity. It records only digests, totals, and machine provenance; source paths, selected bytes, prompts, and secrets never enter this contract.

func BuildReceipt added in v0.4.0 

func BuildReceipt(m ManifestV2) (Receipt, error)

func ParseReceipt added in v0.4.0 

func ParseReceipt(raw []byte) (Receipt, error)

type ResolveError added in v0.4.0 

type ResolveError struct {
	Source string
	Reason string
}

ResolveError names the failing context source so a fail-closed build reports item identity and an actionable finding, never silently dropping required knowledge (R2.3).

func (ResolveError) Error added in v0.4.0 

func (e ResolveError) Error() string

type SelectedTaskV2 added in v0.4.0 

type SelectedTaskV2 struct {
	ID            string   `json:"id"`
	Role          string   `json:"role"`
	DeclaredFiles []string `json:"declared_files"`
	Verify        string   `json:"verify"`
	Acceptance    string   `json:"acceptance"`
}

SelectedTaskV2 carries exact machine-readable task scope. DeclaredFiles is normalized by the byte-stable tasks parser; raw Markdown remains untouched.

type SelectionContext added in v0.4.0 

type SelectionContext struct {
	Phase, Role, TaskID                     string
	Tags, RequirementIDs, TaskFields, Files []string
	// AsOf is caller-supplied aging authority. Zero preserves legacy selection
	// and prevents wall-clock access inside deterministic context construction.
	AsOf               time.Time
	MemoryLintRequired bool
}

SelectionContext is explicit local input for progressive static selection.

type SkillPackage added in v0.4.0 

type SkillPackage struct {
	ID, Version, Trigger, Provenance string
	Phases, Roles, Capabilities      []string
	References                       []string
	Required                         bool
	Budget                           int
	Source, Digest                   string
}

func LoadSkills added in v0.4.0 

func LoadSkills(root string) ([]SkillPackage, error)

type SkillSelectionContext added in v0.4.0 

type SkillSelectionContext struct {
	SelectionContext
	Capabilities []string
}

type TaskEfficiency added in v0.4.0 

type TaskEfficiency struct {
	TaskID               string     `json:"task_id"`
	EstimatedInputTokens *int       `json:"estimated_input_tokens,omitempty"`
	ActualInputTokens    *int       `json:"actual_input_tokens,omitempty"`
	OmittedItems         []Omission `json:"omitted_items,omitempty"`
	RetryCount           int        `json:"retry_count"`
	FirstPassResult      string     `json:"first_pass_result"`
	DurationMS           *int       `json:"duration_ms,omitempty"`
	Cost                 *string    `json:"cost,omitempty"`
}

TaskEfficiency keeps measured quantities nullable. nil means unknown; a pointer to zero means a known zero. This prevents absent telemetry from being presented as free or instantaneous.

type UnsupportedSkillError added in v0.4.0 

type UnsupportedSkillError struct {
	SkillID string
	Reason  string
}

func (UnsupportedSkillError) Error added in v0.4.0 

func (e UnsupportedSkillError) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.