spatialcontract

package
v0.9.1 Latest Latest
Warning

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

 Go to latest Published: Jul 16, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	TypeAsset       = "asset"
	TypeInteraction = "interaction"
)
View Source 
const (
	StateDraft               = "Draft"
	StateTechnicalPassed     = "TechnicalPassed"
	StateAwaitingHumanReview = "AwaitingHumanReview"
	StateApproved            = "Approved"
	StateTechnicalFailed     = "TechnicalFailed"
	StateRevisionRequested   = "RevisionRequested"
	StateUnableToJudge       = "UnableToJudge"
	StateStale               = "Stale"
)
View Source 
const (
	ApprovalActionReview       = "review"
	ApprovalActionApproveApply = "approve_apply"
	// CurrentHashAbsent is the signed compare-and-swap baseline used when the
	// canonical tracked destination did not exist at diff time.
	CurrentHashAbsent = "absent"
)
View Source 
const ContractVersion = 1

Variables

This section is empty.

Functions

func Approve 

func Approve(contract *Contract, reviewer string) error

func CanonicalContractPath 

func CanonicalContractPath(projectRoot string, contract Contract) (string, error)

CanonicalContractPath returns the sole tracked destination for a contract. Interaction target and relation values are UTF-8 hex encoded so filenames are lossless, separator-safe, and collision-free on case-insensitive filesystems.

func ContentHash 

func ContentHash(contract Contract) string

ContentHash is the compatibility form used by already-validated callers. Invalid/non-canonical payloads return an empty, non-authorizable value rather than collapsing onto the SHA-256 of partial encoder output.

func ContentHashChecked 

func ContentHashChecked(contract Contract) (string, error)

func InteractionAssetGUIDs 

func InteractionAssetGUIDs(contract Contract) (string, string, error)

InteractionAssetGUIDs narrows v1 approval to the only dependency shape for which both geometry revisions can currently be proven: SupportedBy between two asset contracts.

func Normalize 

func Normalize(contract *Contract)

func OverlayApprovedAssets 

func OverlayApprovedAssets(manifest *bounds.Manifest, root string) (int, error)

func OverlayApprovedAssetsWithPolicy 

func OverlayApprovedAssetsWithPolicy(manifest *bounds.Manifest, root string, policy OverlayPolicy) (int, error)

OverlayApprovedAssetsWithPolicy overlays only contracts whose approval is verified by the local bridge's external ledger. Legacy tracked approval JSON is deliberately not treated as authority and must be reviewed again.

func ProjectRootForCanonicalContractPath 

func ProjectRootForCanonicalContractPath(path string, contract Contract) (string, error)

ProjectRootForCanonicalContractPath recovers a project root only when path is the exact canonical destination for the validated contract identity.

func ProposalHash 

func ProposalHash(contract Contract) string

ProposalHash is the compatibility form used by already-validated callers. Invalid/non-canonical payloads fail closed with an empty value.

func ProposalHashChecked 

func ProposalHashChecked(contract Contract) (string, error)

ProposalHash identifies the reviewable asset or interaction payload without capture evidence or its recursively derived embedded hash. Capture manifests can bind this value before capture_set_hash exists, and recapturing identical geometry does not manufacture a different proposal identity.

func Review 

func Review(contract *Contract, decision, reviewer string, issues []string, comment string) error

func ReviewAuthorized 

func ReviewAuthorized(contract *Contract, reviewer string, evidence ApprovalEvidence, verifier ApprovalVerifier) error

ReviewAuthorized records an Approved decision only after a trusted local bridge has verified its human-review evidence. It exists for trusted in-process integrations and tests. Production bridges should prefer ApproveAndApplyAuthorized, which consumes a one-shot grant and never leaves an independently writable approved draft behind.

func Save 

func Save(path string, contract Contract) error

func Validate 

func Validate(contract Contract) error

Types

type ApplyResult 

type ApplyResult struct {
	Status       string `json:"status"`
	Current      string `json:"current"`
	Draft        string `json:"draft"`
	Backup       string `json:"backup,omitempty"`
	ContractHash string `json:"contract_hash"`
	Changed      bool   `json:"changed"`
	Written      bool   `json:"written"`
	Verified     bool   `json:"verified"`
}

func Apply 

func Apply(currentPath, draftPath string, write bool) (ApplyResult, error)

func ApplyAuthorized 

func ApplyAuthorized(currentPath, draftPath string, verifier ApprovalVerifier) (ApplyResult, error)

ApplyAuthorized writes an approved draft only after the trusted local bridge re-verifies the exact human approval evidence stored with the review. The public CLI exposes only Apply's read-only dry run.

func ApproveAndApplyAuthorized 

func ApproveAndApplyAuthorized(projectRoot, currentPath, draftPath, expectedCurrentHash, reviewer string, evidence ApprovalEvidence, verifier ApprovalVerifier, consumer ApprovalGrantConsumer) (ApplyResult, error)

ApproveAndApplyAuthorized is the production bridge boundary. It verifies an AwaitingHumanReview draft, binds a signed one-shot grant to the exact content, capture, reviewer and canonical destination, consumes that grant, and writes the Approved contract as one logical operation. Grant evidence is never persisted in the contract.

func ApproveAndApplyAuthorizedWithGeometry 

func ApproveAndApplyAuthorizedWithGeometry(projectRoot, currentPath, draftPath, expectedCurrentHash, reviewer string, evidence ApprovalEvidence, geometry ApprovalGeometryBindings, verifier ApprovalVerifier, consumer ApprovalGrantConsumer) (ApplyResult, error)

ApproveAndApplyAuthorizedWithGeometry is the interaction-aware production boundary. The caller must resolve these hashes from ledger-authorized asset contracts; accepting hashes copied from the interaction caller would make a stale pose appear current without another human review.

type ApprovalEvidence 

type ApprovalEvidence struct {
	Authority   string `json:"authority"`
	Nonce       string `json:"nonce"`
	ExpiresUnix int64  `json:"expires_unix,omitempty"`
	Proof       string `json:"proof"`
}

ApprovalEvidence is an opaque attestation issued by the local human-review bridge. unity-ctx deliberately does not know how to create this evidence; the embedding bridge owns the nonce and proof verification policy.

type ApprovalGeometryBindings 

type ApprovalGeometryBindings struct {
	SubjectGeometryHash    string       `json:"subject_geometry_hash,omitempty"`
	TargetGeometryHash     string       `json:"target_geometry_hash,omitempty"`
	DependencyDestinations []string     `json:"-"`
	RevalidateCurrent      func() error `json:"-"`
}

ApprovalGeometryBindings are resolved from independently approved asset contracts. They are signed with an interaction approval so a caller cannot relabel an old relative pose with whichever geometry hashes are current.

type ApprovalGrantConsumer 

type ApprovalGrantConsumer interface {
	ConsumeApprovalGrant(ApprovalVerification, func() error) error
}

ApprovalGrantConsumer atomically consumes an action-scoped grant after its signature has been verified. Implementations must reject a reused authority/nonce pair. The local review bridge keeps this ledger outside the tracked Unity project.

type ApprovalVerification 

type ApprovalVerification struct {
	Action                 string
	ContractHash           string
	CurrentHash            string
	CaptureSetHash         string
	Reviewer               string
	Destination            string
	SubjectGeometryHash    string
	TargetGeometryHash     string
	DependencyDestinations []string
	RevalidateApplied      func() error
	Evidence               ApprovalEvidence
}

ApprovalVerification is the exact review decision covered by an ApprovalEvidence value. Verifiers must bind all of these fields to the evidence so a proof cannot be replayed for another contract or capture set.

type ApprovalVerifier 

type ApprovalVerifier interface {
	VerifyApproval(ApprovalVerification) error
}

ApprovalVerifier is supplied by the trusted local human-review bridge. The public CLI never supplies a verifier and therefore cannot approve or persist an approved contract.

type ApprovedContractVerification 

type ApprovedContractVerification struct {
	ContractType        string
	ContractHash        string
	CaptureSetHash      string
	Reviewer            string
	ContractPath        string
	SubjectGeometryHash string
	TargetGeometryHash  string
}

ApprovedContractVerification is used when an Approved contract is consumed after the one-shot approval operation (for example by a detailed scan). The verifier is expected to consult the trusted bridge's external approval ledger; StateApproved on its own is never proof of authority.

func ApprovedVerification 

func ApprovedVerification(contract Contract, contractPath string) (ApprovedContractVerification, error)

ApprovedVerification builds the exact, validated ledger lookup for a saved Approved contract. Tracked JSON is not authority by itself; callers must pass the result to an ApprovedContractVerifier before consuming the contract.

type ApprovedContractVerifier 

type ApprovedContractVerifier interface {
	VerifyApprovedContract(ApprovedContractVerification) error
}

type AssetSpatialContract 

type AssetSpatialContract struct {
	AssetGUID        string               `json:"asset_guid"`
	AssetPath        string               `json:"asset_path"`
	DependencyHash   string               `json:"dependency_hash"`
	Units            string               `json:"units"`
	Forward          Vec3                 `json:"forward"`
	Up               Vec3                 `json:"up"`
	PivotOffset      Vec3                 `json:"pivot_offset"`
	CollisionProxies []OBB                `json:"collision_proxies"`
	ClearanceProxies []OBB                `json:"clearance_proxies,omitempty"`
	Frames           []ContactFrame       `json:"frames"`
	Contacts         []ContactRequirement `json:"contacts"`
	Revision         int                  `json:"revision"`
	GeometryHash     string               `json:"geometry_hash"`
	CaptureSetHash   string               `json:"capture_set_hash"`
}

type ContactFrame 

type ContactFrame struct {
	ID      string     `json:"id"`
	Point   Vec3       `json:"point"`
	Normal  Vec3       `json:"normal"`
	Tangent Vec3       `json:"tangent"`
	Size    [2]float64 `json:"size"`
}

type ContactRequirement 

type ContactRequirement struct {
	ID                 string  `json:"id"`
	Kind               string  `json:"kind"`
	FrameID            string  `json:"frame_id"`
	Target             string  `json:"target"`
	MinimumGap         float64 `json:"minimum_gap"`
	MaximumGap         float64 `json:"maximum_gap"`
	MaximumPenetration float64 `json:"maximum_penetration"`
	MinimumSupport     float64 `json:"minimum_support"`
	DirectionAlignment float64 `json:"direction_alignment"`
}

type Contract 

type Contract struct {
	ContractVersion int                   `json:"contract_version"`
	ContractType    string                `json:"contract_type"`
	State           string                `json:"state"`
	Asset           *AssetSpatialContract `json:"asset,omitempty"`
	Interaction     *InteractionContract  `json:"interaction,omitempty"`
	Technical       *TechnicalEvidence    `json:"technical,omitempty"`
	Review          *HumanReview          `json:"review,omitempty"`
}

func Decode 

func Decode(data []byte) (Contract, error)

func Load 

func Load(path string) (Contract, error)

type DiffResult 

type DiffResult struct {
	Status              string   `json:"status"`
	Current             string   `json:"current"`
	Draft               string   `json:"draft"`
	ContractType        string   `json:"contract_type"`
	ContractHash        string   `json:"contract_hash"`
	ProposalHash        string   `json:"proposal_hash"`
	CurrentHash         string   `json:"current_hash"`
	AssetGUID           string   `json:"asset_guid,omitempty"`
	GeometryHash        string   `json:"geometry_hash,omitempty"`
	SubjectGUID         string   `json:"subject_guid,omitempty"`
	TargetKey           string   `json:"target_key,omitempty"`
	SubjectGeometryHash string   `json:"subject_geometry_hash,omitempty"`
	TargetGeometryHash  string   `json:"target_geometry_hash,omitempty"`
	Changed             bool     `json:"changed"`
	Fields              []string `json:"fields"`
}

func Diff 

func Diff(currentPath, draftPath string) (DiffResult, error)

type HumanReview 

type HumanReview struct {
	Decision       string            `json:"decision"`
	ContractHash   string            `json:"contract_hash"`
	CaptureSetHash string            `json:"capture_set_hash"`
	Reviewer       string            `json:"reviewer"`
	Authorization  *ApprovalEvidence `json:"authorization,omitempty"`
	IssueTypes     []string          `json:"issue_types,omitempty"`
	Comment        string            `json:"comment,omitempty"`
	Revision       int               `json:"revision"`
}

type InteractionContract 

type InteractionContract struct {
	SubjectGUID       string  `json:"subject_guid"`
	TargetKey         string  `json:"target_key"`
	Relation          string  `json:"relation"`
	SubjectFrame      string  `json:"subject_frame"`
	TargetFrame       string  `json:"target_frame"`
	RelativePosition  Vec3    `json:"relative_position"`
	RelativeRotation  Quat    `json:"relative_rotation"`
	PositionTolerance Vec3    `json:"position_tolerance"`
	AngleTolerance    float64 `json:"angle_tolerance"`
	CollisionPolicy   string  `json:"collision_policy"`
	Revision          int     `json:"revision"`
	InteractionHash   string  `json:"interaction_hash"`
	CaptureSetHash    string  `json:"capture_set_hash"`
}

type OBB 

type OBB struct {
	ID       string `json:"id"`
	Center   Vec3   `json:"center"`
	Size     Vec3   `json:"size"`
	Rotation Quat   `json:"rotation"`
}

type OverlayPolicy 

type OverlayPolicy struct {
	Verifier ApprovedContractVerifier
}

type Quat 

type Quat [4]float64

type TechnicalEvidence 

type TechnicalEvidence struct {
	Passed     bool   `json:"passed"`
	ErrorCount int    `json:"error_count"`
	ReportHash string `json:"report_hash"`
}

type Vec3 

type Vec3 [3]float64

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.