source

type Identity struct {
	// Name is a stable identifier such as "devproof.thingz.io/path/v1".
	Name string `json:"name"`
	// Version is the implementation version.
	Version string `json:"version"`
}

type Material struct {
	// Type is the manifest source type.
	Type string
	// Resolver identifies the implementation.
	Resolver Identity

	// Requested is what the manifest asked for, which may be mutable.
	Requested map[string]any
	// Resolved is what it resolved to, which must be immutable. A resolver
	// that cannot produce an immutable resolution must fail rather than
	// record a moving reference.
	Resolved map[string]any

	// TreeDigest is the canonical digest of the filtered, source-relative
	// contribution.
	TreeDigest bundle.Digest
}

type ResolveRequest struct {
	// Name is the logical source name, for diagnostics and evidence.
	Name string
	// Config is the resolver-specific configuration from the manifest.
	Config map[string]any

	// Include and Exclude filter source-relative paths before composition.
	Include []string
	Exclude []string

	// BaseDir is the manifest's directory. Relative local paths resolve
	// against it rather than the process working directory, so a manifest
	// means the same thing wherever it is invoked from (DP-012).
	BaseDir string

	// Locked, when set, is the resolution this build must reproduce.
	Locked *bundle.LockedSource

	// Limits bounds what the resolver may produce.
	Limits bundle.Limits

	// TempRoot is the parent for private snapshot storage.
	TempRoot string
}

type Resolver interface {
	// Type is the manifest source type this resolver handles, such as
	// "path", or a domain-qualified name for an extension.
	Type() string

	// Identity names the implementation and its version. It is recorded in
	// the lock, so a resolver whose behavior changes cannot silently satisfy
	// a lock an earlier version produced.
	Identity() Identity

	// Resolve obtains material and returns a frozen snapshot.
	//
	// When the request carries a Locked source, the resolver must reproduce
	// exactly that resolution and report a stale-lock error if it cannot.
	Resolve(ctx context.Context, req ResolveRequest) (Snapshot, error)
}

type Snapshot interface {
	// Material describes what was resolved, in terms safe to publish.
	Material() Material

	// Records returns the canonical file records, source-relative and sorted
	// by path.
	Records() []bundle.FileRecord

	// Open returns the content of a path previously returned by Records.
	Open(ctx context.Context, path bundle.Path) (io.ReadCloser, error)

	// Close releases the snapshot's private storage.
	Close() error
}