doccompiler

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Sep 24, 2026 License: AGPL-3.0, AGPL-3.0-or-later Imports: 28 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ClauseSupported  = "SUPPORTED"
	ClauseConflicted = "CONFLICTED"
	ClauseUnknown    = "UNKNOWN"

	KindPrescriptive = "PRESCRIPTIVE"
	KindDescriptive  = "DESCRIPTIVE"

	ScopeObserved = "OBSERVED"
	ScopeGeneral  = "GENERAL"

	FrontierNoQualifyingSource = "NO_QUALIFYING_SOURCE"
	FrontierStaleAnchor        = "STALE_ANCHOR"
	FrontierResolverUndecided  = "RESOLVER_UNDECIDED"

	AuthorityAcceptedIntent   = "ACCEPTED_INTENT"
	AuthorityPinnedSource     = "PINNED_SOURCE"
	AuthorityPinnedTest       = "PINNED_TEST"
	AuthorityExecutionReceipt = "EXECUTION_RECEIPT"

	// ProseTemplateSet names the closed, versioned template set of HDCV0-026.
	ProseTemplateSet = "corvint-hdc-prose-templates/0"
)

Closed clause vocabularies of HDCV0-023..025.

View Source 
const (
	PlanEnvironmentPlanOnly = "plan-only"
	PlanSnapshotNotRun      = "NOT_RUN"

	OperationCreateFile  = "create_file"
	OperationInsertAfter = "insert_after"
	OperationEditNav     = "edit_nav"

	TargetAbsent  = "ABSENT"
	TargetPresent = "PRESENT"
)

Closed vocabularies of the admitted HDCV0-027..029 plan wire (decision 0231).

View Source 
const (
	Profile         = "corvint-human-documentation-compiler/0"
	PlanProfile     = "corvint-human-documentation-plan/0"
	ReceiptProfile  = "corvint-human-documentation-receipt/0"
	MaterialProfile = "mkdocs-material/qualified-p0"
)
View Source 
const DraftMaxBytes = 64 << 10
View Source 
const ExperimentalPatchPlanProfile = "corvint-human-documentation-experimental-patch-plan/0"

ExperimentalPatchPlanProfile names the experimental PatchPlan that Plan emits and Build consumes. It is not the HDCV0-027 wire (decision 0240).

View Source 
const MaxCanonicalJSONBytes = 8 << 20

MaxCanonicalJSONBytes is the HDCV0 limit on one canonical plan or receipt.

Variables

This section is empty.

Functions

func BuildDigest 

func BuildDigest(result BuildResult) (string, error)

func CanonicalJSON 

func CanonicalJSON(value any) ([]byte, error)

CanonicalJSON emits the HDCV0-041 canonical encoding of value, including the trailing LF. VerifyCanonicalJSON accepts every byte string it returns; a value with a non-integer number or a canonical form over 8 MiB is refused.

func CanonicalJSONUnbounded 

func CanonicalJSONUnbounded(value any) ([]byte, error)

CanonicalJSONUnbounded emits the same HDCV0-041 bytes as CanonicalJSON without the 8 MiB plan/receipt bound. It serves a downstream profile that owns its own output limit (CATN-V0-012); that caller MUST enforce the limit.

func CanonicalReceipt 

func CanonicalReceipt(receipt Receipt) ([]byte, string, error)

func CompileAdmittedPlan 

func CompileAdmittedPlan(index *contextindex.Index, request AdmittedPlanRequest) ([]byte, []byte, error)

CompileAdmittedPlan admits the request clauses (HDCV0-023..026) and emits the canonical plan plus the proposal patch whose SHA-256 the plan binds. It reads only index and never touches a worktree or starts a process.

func ConsumeDraft 

func ConsumeDraft(draft SourceDraft, provided []byte, task string) (map[string]any, error)

ConsumeDraft checks bytes against the supplied draft and builds ephemeral orientation postings. Only a caller that freshly rederives original Git sources can attach SOURCE_REDERIVED validation; this pure helper makes no such claim.

func RenderAdmittedProse 

func RenderAdmittedProse(index *contextindex.Index, clauses []Clause) ([]byte, error)

RenderAdmittedProse admits clauses and renders them with only the closed ProseTemplateSet strings. Caller-supplied values are rendered as literals.

func StaleOperations 

func StaleOperations(index *contextindex.Index, plan AdmittedPlan) []string

StaleOperations reports, in plan order, the operations whose precondition no longer holds at index (HDCV0-029). The plan is retained and never retargeted.

func VerifyAdmittedProse 

func VerifyAdmittedProse(index *contextindex.Index, clauses []Clause, candidate []byte) error

VerifyAdmittedProse refuses a candidate transformation unless it is exactly the rendering of its admitted clauses: any other sentence is refused.

func VerifyCanonicalJSON 

func VerifyCanonicalJSON(raw []byte) error

VerifyCanonicalJSON accepts raw only when it is exactly the HDCV0-041 canonical encoding of its own parsed value, including the trailing LF.

func VerifyReceipt 

func VerifyReceipt(receipt Receipt) error

Types

type AdmittedPlan 

type AdmittedPlan struct {
	Profile               string                    `json:"profile"`
	SourceIdentity        PlanSourceIdentity        `json:"source_identity"`
	EnvironmentPin        PlanEnvironmentPin        `json:"environment_pin"`
	ConfigurationSnapshot PlanConfigurationSnapshot `json:"configuration_snapshot"`
	Clauses               []Clause                  `json:"clauses"`
	Operations            []PlanOperation           `json:"operations"`
	CandidatePatchSHA256  string                    `json:"candidate_patch_sha256"`
	Uncertainty           []string                  `json:"uncertainty"`
	LimitsConsumed        PlanLimits                `json:"limits_consumed"`
	Exclusions            []PlanExclusion           `json:"exclusions"`
}

AdmittedPlan is the closed corvint-human-documentation-plan/0 wire of HDCV0-027. Build, offline, and artifact digests are receipt-only and have no member here.

func VerifyAdmittedPlan 

func VerifyAdmittedPlan(index *contextindex.Index, raw, patch []byte) (AdmittedPlan, error)

VerifyAdmittedPlan decodes a canonical plan strictly and refuses it unless recompiling its clauses and operations at index reproduces the plan and patch bytes.

type AdmittedPlanRequest 

type AdmittedPlanRequest struct {
	Clauses   []Clause
	Documents []PlanDocument
}

AdmittedPlanRequest is the plan-only compiler input: candidate clauses and the documentation targets that should carry their admitted rendering.

type Anchor 

type Anchor struct {
	Path       string `json:"path"`
	Blob       string `json:"blob"`
	StartLine  int    `json:"start_line"`
	EndLine    int    `json:"end_line"`
	SpanSHA256 string `json:"span_sha256"`
	Authority  string `json:"authority"`
	Reason     string `json:"reason"`
}

Anchor is the evidence-anchor definition: every member is required.

type BuildOptions 

type BuildOptions struct {
	OutputParent     string
	Timeout          time.Duration
	MaxStdoutBytes   int
	MaxStderrBytes   int
	MaxSourceBytes   int64
	MaxCorpusBytes   int64
	MaxOutputBytes   int64
	MaxOutputFiles   int
	TrustAttestation EnvironmentTrustAttestation
}

type BuildResult 

type BuildResult struct {
	BuildStrictStatus       string   `json:"build_strict_status"`
	OfflineQualification    string   `json:"offline_qualification"`
	Argv                    []string `json:"argv"`
	OutputRoot              string   `json:"-"`
	OutputSHA256            string   `json:"output_sha256,omitempty"`
	OutputBytes             int64    `json:"output_bytes"`
	OutputFiles             int      `json:"output_files"`
	Stdout                  string   `json:"stdout,omitempty"`
	Stderr                  string   `json:"stderr,omitempty"`
	DocumentCandidatesBuilt bool     `json:"document_candidates_built"`
	NavCandidateBuilt       bool     `json:"nav_candidate_built"`
	OfflineEnforcement      string   `json:"offline_enforcement"`
	ProcessContainment      string   `json:"process_containment"`
	Uncertainty             []string `json:"uncertainty"`
}

func QualifyOffline 

func QualifyOffline(result BuildResult, _ OfflineAttestation) (BuildResult, error)

QualifyOffline cannot promote a completed build from caller-supplied claims. P0 has no concrete external denial-harness integration, so no code path sets PASS.

type BytePatch 

type BytePatch struct {
	StartByte         int    `json:"start_byte"`
	EndByte           int    `json:"end_byte"`
	OriginalSHA256    string `json:"original_sha256"`
	ReplacementSHA256 string `json:"replacement_sha256"`
	Replacement       string `json:"replacement"`
}

type Claim 

type Claim struct {
	ID          string     `json:"id"`
	Status      string     `json:"status"`
	Text        string     `json:"text"`
	Uncertainty string     `json:"uncertainty,omitempty"`
	Evidence    []Evidence `json:"evidence"`
}

type Clause 

type Clause struct {
	ID       string   `json:"id"`
	State    string   `json:"state"`
	Kind     string   `json:"kind"`
	Scope    string   `json:"scope"`
	Text     string   `json:"text"`
	Frontier string   `json:"frontier,omitempty"`
	Anchors  []Anchor `json:"anchors"`
}

Clause is one HDCV0-023 output clause. Frontier is empty unless State is UNKNOWN.

func AdmitClauses 

func AdmitClauses(index *contextindex.Index, clauses []Clause) ([]Clause, error)

AdmitClauses applies HDCV0-023..025 against the Git-pinned sources of index. A malformed clause is refused. A SUPPORTED or CONFLICTED clause whose qualifying anchors do not establish that state is admitted as UNKNOWN with a frontier and keeps its anchors as review context; no state is ever upgraded.

type Compiler 

type Compiler struct{}

func New 

func New() *Compiler

func (*Compiler) Plan 

func (compiler *Compiler) Plan(environment Environment, options PlanOptions) (PatchPlan, error)

Plan currently admits only UNKNOWN claims with an explicit uncertainty frontier and no Evidence. Working-tree source pins are patch preconditions, not immutable evidence or acceptance authority. SUPPORTED and CONFLICTED require a future immutable-source and authority verifier.

type ConfigObservations 

type ConfigObservations struct {
	Authority                string         `json:"authority"`
	ParserStatus             string         `json:"parser_status"`
	DocsDir                  string         `json:"docs_dir"`
	SiteDir                  string         `json:"site_dir"`
	NavConfigured            bool           `json:"nav_configured"`
	NavMode                  string         `json:"nav_mode"`
	NavOwner                 string         `json:"nav_owner"`
	NavSHA256                string         `json:"nav_sha256"`
	SiteURL                  string         `json:"site_url,omitempty"`
	UseDirectoryURLs         bool           `json:"use_directory_urls"`
	ThemeName                string         `json:"theme_name,omitempty"`
	ThemeOptionsSHA256       string         `json:"theme_options_sha256"`
	ThemeFeatures            []string       `json:"theme_features"`
	ThemeCustomDir           string         `json:"theme_custom_dir,omitempty"`
	PluginsConfigured        bool           `json:"plugins_configured"`
	Plugins                  []string       `json:"plugins"`
	PluginOptions            []OptionDigest `json:"plugin_options"`
	SearchStatus             string         `json:"search_status"`
	MarkdownExtensions       []string       `json:"markdown_extensions"`
	MarkdownExtensionOptions []OptionDigest `json:"markdown_extension_options"`
	ExtraCSS                 []string       `json:"extra_css"`
	ExtraJavaScript          []string       `json:"extra_javascript"`
	Hooks                    []string       `json:"hooks"`
	InheritsConfig           bool           `json:"inherits_config"`
	ValidationConfigured     bool           `json:"validation_configured"`
	ValidationSHA256         string         `json:"validation_sha256"`
	Validation               map[string]any `json:"validation"`
	PrivacySettings          []string       `json:"privacy_settings"`
	OfflineRelated           []string       `json:"offline_related"`
	RemoteAssets             []string       `json:"remote_assets"`
	Uncertainty              []string       `json:"uncertainty"`
}

type DiscoverOptions 

type DiscoverOptions struct {
	ProjectRoot               string
	MkDocsPath                string
	PythonPath                string
	ConfigPath                string
	ProjectLockPath           string
	ExpectedProjectLockSHA256 string
	ExpectedMkDocsVersion     string
	ExpectedMaterialVersion   string
	ExpectedMarkdownVersion   string
	ExpectedPyMdownVersion    string
	MaxCommandBytes           int
	MaxConfigBytes            int64
	TrustAttestation          EnvironmentTrustAttestation
}

DiscoverOptions names a project-owned environment explicitly. No PATH lookup or dependency installation is performed.

type Distribution 

type Distribution struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

type DocumentPatch 

type DocumentPatch struct {
	Path             string    `json:"path"`
	Operation        string    `json:"operation"`
	ReviewRequired   bool      `json:"review_required"`
	CurrentSHA256    string    `json:"current_sha256,omitempty"`
	ProposedSHA256   string    `json:"proposed_sha256"`
	Patch            BytePatch `json:"patch"`
	RenderedMarkdown string    `json:"-"`
	Claims           []Claim   `json:"claims"`
}

type DocumentProposal 

type DocumentProposal struct {
	Path string
	// Markdown must be empty until prose can be admitted clause by clause.
	Markdown string
	Claims   []Claim
}

type DraftEntry 

type DraftEntry struct {
	ID        string `json:"id"`
	Kind      string `json:"kind"`
	Title     string `json:"title"`
	Excerpt   string `json:"excerpt"`
	Path      string `json:"path"`
	Blob      string `json:"blob"`
	SHA256    string `json:"sha256"`
	StartLine int    `json:"start_line"`
	EndLine   int    `json:"end_line"`
}

type Environment 

type Environment struct {
	ProjectRoot   string             `json:"-"`
	Toolchain     Toolchain          `json:"toolchain"`
	Config        FilePin            `json:"config"`
	Observations  ConfigObservations `json:"observations"`
	Qualification string             `json:"qualification"`
}

type EnvironmentTrustAttestation 

type EnvironmentTrustAttestation struct {
	Profile           string `json:"profile"`
	EnvironmentSHA256 string `json:"environment_sha256"`
	Authority         string `json:"authority"`
	Revision          string `json:"revision"`
}

type Error 

type Error struct {
	Code    string
	Message string
}

func (*Error) Error 

func (problem *Error) Error() string

type Evidence 

type Evidence struct {
	Path       string `json:"path"`
	SHA256     string `json:"sha256"`
	Revision   string `json:"revision"`
	StartLine  int    `json:"start_line"`
	EndLine    int    `json:"end_line"`
	Authority  string `json:"authority"`
	Confidence string `json:"confidence"`
}

type FilePin 

type FilePin struct {
	Path         string `json:"path"`
	ResolvedPath string `json:"resolved_path,omitempty"`
	SHA256       string `json:"sha256"`
	Size         int64  `json:"size"`
}
type NavEntry struct {
	Title string `json:"title"`
	Path  string `json:"path"`
}
type NavPatch struct {
	ConfigPath        string     `json:"config_path"`
	ConfigSHA256      string     `json:"config_sha256"`
	Operation         string     `json:"operation"`
	ReviewRequired    bool       `json:"review_required"`
	CurrentNavSHA256  string     `json:"current_nav_sha256"`
	ProposedNavSHA256 string     `json:"proposed_nav_sha256"`
	Patch             BytePatch  `json:"patch"`
	Entries           []NavEntry `json:"entries"`
}

type OfflineAttestation 

type OfflineAttestation struct {
	Profile           string `json:"profile"`
	BuildSHA256       string `json:"build_sha256"`
	Authority         string `json:"authority"`
	Method            string `json:"method"`
	AttestationSHA256 string `json:"attestation_sha256"`
}

type OptionDigest 

type OptionDigest struct {
	Name          string `json:"name"`
	OptionsSHA256 string `json:"options_sha256"`
}

type PatchPlan 

type PatchPlan struct {
	Profile      string          `json:"profile"`
	ConfigSHA256 string          `json:"config_sha256"`
	Documents    []DocumentPatch `json:"documents"`
	Nav          NavPatch        `json:"nav"`
	Evidence     []Evidence      `json:"evidence"`
	Sources      []SourcePin     `json:"sources"`
	PlanSHA256   string          `json:"plan_sha256"`
}

type PlanConfigurationSnapshot 

type PlanConfigurationSnapshot struct {
	Status string `json:"status"`
}

PlanConfigurationSnapshot records that no MkDocs loader ran for a plan-only request.

type PlanDocument 

type PlanDocument struct {
	ID        string
	Target    string
	ClauseIDs []string
	Reason    string
}

type PlanEnvironmentPin 

type PlanEnvironmentPin struct {
	Kind string `json:"kind"`
}

PlanEnvironmentPin is the HDCV0-CAP-001 plan-only variant; no execution pin is admitted.

type PlanExclusion 

type PlanExclusion struct {
	Code string `json:"code"`
	Path string `json:"path"`
}

type PlanLimits 

type PlanLimits struct {
	Anchors     int `json:"anchors"`
	Clauses     int `json:"clauses"`
	Operations  int `json:"operations"`
	SourceBytes int `json:"source_bytes"`
	SourceFiles int `json:"source_files"`
}

type PlanOperation 

type PlanOperation struct {
	ID                string   `json:"id"`
	Kind              string   `json:"kind"`
	Target            string   `json:"target"`
	TargetState       string   `json:"target_state"`
	TargetBlob        string   `json:"target_blob"`
	TargetSHA256      string   `json:"target_sha256"`
	StartByte         int      `json:"start_byte"`
	EndByte           int      `json:"end_byte"`
	ReplacementSHA256 string   `json:"replacement_sha256"`
	ClauseIDs         []string `json:"clause_ids"`
	Reason            string   `json:"reason"`
}

PlanOperation is one HDCV0-028 operation with its optimistic-concurrency precondition.

type PlanOptions 

type PlanOptions struct {
	Documents []DocumentProposal
	Nav       []NavEntry
}

type PlanSource 

type PlanSource struct {
	Path   string `json:"path"`
	Mode   string `json:"mode"`
	Blob   string `json:"blob"`
	SHA256 string `json:"sha256"`
}

type PlanSourceIdentity 

type PlanSourceIdentity struct {
	Revision string       `json:"revision"`
	Sources  []PlanSource `json:"sources"`
}

PlanSourceIdentity is the Git revision plus every consumed source, ordered by path.

type Receipt 

type Receipt struct {
	Profile             string             `json:"profile"`
	DeliveryStage       string             `json:"delivery_stage"`
	Claim               string             `json:"claim"`
	MaterialProfile     string             `json:"material_profile"`
	Toolchain           Toolchain          `json:"toolchain"`
	Config              FilePin            `json:"config"`
	ConfigObservations  ConfigObservations `json:"config_observations"`
	ConfigQualification string             `json:"config_qualification"`
	PlanSHA256          string             `json:"plan_sha256"`
	Build               BuildResult        `json:"build"`
	Evidence            []ReceiptEvidence  `json:"evidence"`
	Uncertainty         []string           `json:"uncertainty"`
}

func NewReceipt 

func NewReceipt(environment Environment, plan PatchPlan, build BuildResult) (Receipt, error)

type ReceiptEvidence 

type ReceiptEvidence struct {
	ClaimID    string `json:"claim_id"`
	Path       string `json:"path"`
	SHA256     string `json:"sha256"`
	Revision   string `json:"revision"`
	StartLine  int    `json:"start_line"`
	EndLine    int    `json:"end_line"`
	Authority  string `json:"authority"`
	Confidence string `json:"confidence"`
	Reason     string `json:"reason"`
}

type SourceDraft 

type SourceDraft struct {
	Markdown     []byte
	Entries      []DraftEntry
	Commit, Tree string
	Limitations  []string
}

func DraftSources 

func DraftSources(index *contextindex.Index, sourcePath, directory string) (SourceDraft, error)

DraftSources compiles orientation only. It never creates an HDC plan, grants authority, or interprets source prose as proof of implementation behavior.

type SourcePin 

type SourcePin struct {
	Path   string `json:"path"`
	SHA256 string `json:"sha256"`
	Size   int64  `json:"size"`
}

type Toolchain 

type Toolchain struct {
	MkDocs            FilePin        `json:"mkdocs"`
	Python            FilePin        `json:"python"`
	ProjectLock       FilePin        `json:"project_lock"`
	MkDocsVersion     string         `json:"mkdocs_version"`
	MaterialVersion   string         `json:"material_version"`
	MarkdownVersion   string         `json:"markdown_version"`
	PyMdownVersion    string         `json:"pymdown_extensions_version,omitempty"`
	PythonVersion     string         `json:"python_version"`
	EnvironmentSHA256 string         `json:"environment_sha256"`
	DistributionCount int            `json:"distribution_count"`
	Distributions     []Distribution `json:"distributions"`
}

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.