Documentation
¶
Overview ¶
Package prototypes owns the optional v3 prototype capability of a living Change Saga. It is deliberately independent of the Saga loader, CLI, query registry, server, and requirements package; cross-domain checks happen only through Compose.
Index ¶
- Constants
- func AnnotationURN(sagaID, prototypeID, annotationID string) (string, error)
- func PrototypeURN(sagaID, prototypeID string) (string, error)
- func ReadPinnedStyle(repositoryRoot string, style StyleSource) ([]byte, error)
- func RevisionURN(sagaID, prototypeID, revisionID string) (string, error)
- type AddAnnotationInput
- type AddExternalInput
- type AddHTMLInput
- type AddStyleInput
- type Annotation
- type AnnotationProjection
- type CompositionInputs
- type CoverageProjection
- type Document
- type Identity
- type LoadOptions
- type MutationResult
- func AddAnnotation(root, sagaID string, input AddAnnotationInput) (MutationResult, error)
- func AddExternal(root, sagaID string, input AddExternalInput) (MutationResult, error)
- func AddExternalPrototype(root, sagaID string, input AddExternalInput) (MutationResult, error)
- func AddHTML(root, sagaID string, input AddHTMLInput) (MutationResult, error)
- func AddHTMLPrototype(root, sagaID string, input AddHTMLInput) (MutationResult, error)
- func AddRepositoryStyle(root, sagaID string, input AddStyleInput) (MutationResult, error)
- func AddStyle(root, sagaID string, input AddStyleInput) (MutationResult, error)
- func Annotate(root, sagaID string, input AddAnnotationInput) (MutationResult, error)
- func RefreshRepositoryStyle(root, sagaID string, input AddStyleInput) (MutationResult, error)
- func Revise(root, sagaID string, input ReviseInput) (MutationResult, error)
- func RevisePrototype(root, sagaID string, input ReviseInput) (MutationResult, error)
- type Prototype
- type ProviderAllowlist
- type QualityGap
- type Region
- type ResourceCoverage
- type ReviseInput
- type Revision
- type Selector
- type SelectorKind
- type Source
- type SourceKind
- type State
- type StoryInput
- type StyleRole
- type StyleSource
Constants ¶
const ( Version = 3 IdentitySchemaURL = "https://changesaga.dev/schema/v3/prototype.schema.json" RevisionSchemaURL = "https://changesaga.dev/schema/v3/prototype-revision.schema.json" AnnotationSchemaURL = "https://changesaga.dev/schema/v3/prototype-annotation.schema.json" MaxPrototypes = 10_000 MaxRevisionsPerPrototype = 10_000 MaxAnnotations = 50_000 MaxRecordBytes = 1 << 20 MaxHTMLFiles = 2_000 MaxHTMLFileBytes = 8 << 20 MaxHTMLPackageBytes = 64 << 20 )
Variables ¶
This section is empty.
Functions ¶
func AnnotationURN ¶
func PrototypeURN ¶
func ReadPinnedStyle ¶
func ReadPinnedStyle(repositoryRoot string, style StyleSource) ([]byte, error)
ReadPinnedStyle returns repository CSS only when the requested declaration is safe and still matches its SHA-256 pin. Viewers can use this as the sole style-serving boundary instead of opening arbitrary repository paths.
func RevisionURN ¶
Types ¶
type AddAnnotationInput ¶
type AddExternalInput ¶
type AddHTMLInput ¶
type AddStyleInput ¶
type Annotation ¶
type Annotation struct {
Schema string `json:"$schema"`
Version int `json:"version"`
ID string `json:"id"`
Prototype string `json:"prototype"`
Target string `json:"target"`
Rationale string `json:"rationale"`
PrototypeRevision string `json:"prototype_revision,omitempty"`
PrototypeContentDigest string `json:"prototype_content_digest,omitempty"`
StoryRevision string `json:"story_revision"`
Selector Selector `json:"selector"`
CreatedAt time.Time `json:"created_at"`
RequestID string `json:"request_id,omitempty"`
}
Annotation is the single persisted edge between a prototype and a story or criterion. Endpoint existence is intentionally not a record-level rule.
type AnnotationProjection ¶
type AnnotationProjection struct {
Annotation Annotation `json:"annotation"`
PrototypeResolved bool `json:"prototype_resolved"`
TargetResolved bool `json:"target_resolved"`
Current bool `json:"current"`
StaleReasons []string `json:"stale_reasons"`
}
type CompositionInputs ¶
type CompositionInputs struct {
Stories []StoryInput
}
CompositionInputs are owned by the caller so this package does not import the requirements domain. They describe only the current requirement heads.
type CoverageProjection ¶
type CoverageProjection struct {
Capability string `json:"capability"`
Annotations []AnnotationProjection `json:"annotations"`
Prototypes []ResourceCoverage `json:"prototypes"`
Stories []ResourceCoverage `json:"stories"`
Gaps []QualityGap `json:"gaps"`
}
func Compose ¶
func Compose(document Document, inputs CompositionInputs) CoverageProjection
Compose resolves the prototype domain against a caller-supplied requirements snapshot. Missing endpoints and stale pins become quality gaps, never structural load errors. The returned edge list is the one source for both prototype-to-story and story-to-prototype projections.
func ProjectCoverage ¶
func ProjectCoverage(document Document, inputs CompositionInputs) CoverageProjection
ProjectCoverage is a naming alias suited to query adapters.
type Document ¶
type Document struct {
Root string
SagaID string
Adopted bool
Prototypes []Prototype
Annotations []Annotation
}
func LoadWithOptions ¶
func LoadWithOptions(root, sagaID string, options LoadOptions) (Document, error)
LoadWithOptions reads only saga.json and ___requirements/prototypes. It never follows symlinks or opens stories, narrative, design, work-plan, review, or diff data.
type LoadOptions ¶
type LoadOptions struct {
// RepositoryRoot is optional. When supplied, declared repository CSS is
// re-read safely and its projection is marked stale if its pin changed.
RepositoryRoot string
}
type MutationResult ¶
func AddAnnotation ¶
func AddAnnotation(root, sagaID string, input AddAnnotationInput) (MutationResult, error)
func AddExternal ¶
func AddExternal(root, sagaID string, input AddExternalInput) (MutationResult, error)
func AddExternalPrototype ¶
func AddExternalPrototype(root, sagaID string, input AddExternalInput) (MutationResult, error)
func AddHTML ¶
func AddHTML(root, sagaID string, input AddHTMLInput) (MutationResult, error)
func AddHTMLPrototype ¶
func AddHTMLPrototype(root, sagaID string, input AddHTMLInput) (MutationResult, error)
AddHTMLPrototype is an explicit-name alias for adapters that prefer the resource noun in mutation calls.
func AddRepositoryStyle ¶
func AddRepositoryStyle(root, sagaID string, input AddStyleInput) (MutationResult, error)
func AddStyle ¶
func AddStyle(root, sagaID string, input AddStyleInput) (MutationResult, error)
AddStyle appends a revision that pins one validated repository stylesheet. The prior immutable HTML tree is copied into the new revision package.
func Annotate ¶
func Annotate(root, sagaID string, input AddAnnotationInput) (MutationResult, error)
func RefreshRepositoryStyle ¶
func RefreshRepositoryStyle(root, sagaID string, input AddStyleInput) (MutationResult, error)
func Revise ¶
func Revise(root, sagaID string, input ReviseInput) (MutationResult, error)
Revise appends a complete revision. HTML revisions must provide a fresh HTMLSourcePath; this prevents a mutable directory outside the Saga from becoming an implicit part of the revision.
func RevisePrototype ¶
func RevisePrototype(root, sagaID string, input ReviseInput) (MutationResult, error)
type Prototype ¶
type Prototype struct {
Identity Identity
Revisions []Revision
RevisionHeads []string
CurrentRevision *Revision
}
func (Prototype) RevisionConflict ¶
type ProviderAllowlist ¶
type QualityGap ¶
type ResourceCoverage ¶
type ReviseInput ¶
type Revision ¶
type Revision struct {
Schema string `json:"$schema"`
Version int `json:"version"`
ID string `json:"id"`
Prototype string `json:"prototype"`
Parents []string `json:"parents"`
Title string `json:"title"`
State State `json:"state"`
Source Source `json:"source"`
Styles []StyleSource `json:"styles"`
CreatedAt time.Time `json:"created_at"`
RequestID string `json:"request_id,omitempty"`
}
Revision is a complete snapshot. Source files for an HTML revision are immutable children of the same <id>.revision package as revision.json.
type SelectorKind ¶
type SelectorKind string
const ( SelectorElement SelectorKind = "element" SelectorText SelectorKind = "text" SelectorRegion SelectorKind = "region" SelectorProvider SelectorKind = "provider" )
type Source ¶
type Source struct {
Kind SourceKind `json:"kind"`
Entrypoint string `json:"entrypoint,omitempty"`
ContentDigest string `json:"content_digest,omitempty"`
URL string `json:"url,omitempty"`
EmbedURL string `json:"embed_url,omitempty"`
FallbackURL string `json:"fallback_url,omitempty"`
Allowlist *ProviderAllowlist `json:"allowlist,omitempty"`
}
Source is a closed discriminated union. HTML paths are relative to their immutable revision package. Embed allowlisting is persisted explicitly so a viewer never infers permission merely from a recognizable hostname.
type SourceKind ¶
type SourceKind string
const ( SourceHTML SourceKind = "html" SourceExternal SourceKind = "external" SourceEmbed SourceKind = "embed" )