artifact

type Artifact struct {
	ID        string `json:"id"`
	SpaceID   string `json:"space_id"`
	Filename  string `json:"filename"`
	MediaType string `json:"media_type"`
	SizeBytes int64  `json:"size_bytes"`
	SHA256    string `json:"sha256"`
	// StorageKey is where the object store put the bytes. It is never
	// serialized: an API response, tool output, trace, or audit event that
	// carried it would leak deployment layout and outlive the layout's freedom
	// to change.
	//
	// It is also the record of whether the bytes are still held. Every artifact
	// gets a key when it is created, so an empty one means retention has
	// reclaimed the object — see Purged. That is why the purge sweep clears it
	// rather than adding a column: "no key" and "nothing stored" are the same
	// fact, and two columns that must agree eventually will not.
	StorageKey    string `json:"-"`
	CreatedByType string `json:"created_by_type"`
	CreatedByID   string `json:"created_by_id"`
	SourceType    string `json:"source_type"`
	SourceID      string `json:"source_id,omitempty"`
	Title         string `json:"title,omitempty"`
	// DeletedAt tombstones the artifact. Metadata and content stop being
	// served the moment it is set; removing the object itself is a later,
	// separate step under retention policy.
	DeletedAt *time.Time `json:"deleted_at,omitempty"`
	// ExpiresAt tombstones the artifact once it passes, applied by the
	// retention sweep. An artifact with none is kept until somebody deletes it.
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
	CreatedAt time.Time  `json:"created_at"`
}

type ArtifactShare struct {
	ShareID       string `json:"share_id"`
	ArtifactID    string `json:"artifact_id"`
	SpaceID       string `json:"space_id"`
	CreatedByType string `json:"created_by_type"`
	CreatedByID   string `json:"created_by_id,omitempty"`
	// ExpiresAt bounds the link; nil is a link with no expiry (still revocable).
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
	// RevokedAt withdraws the link. A revoked share resolves to the same 404 a
	// never-existed token gives.
	RevokedAt       *time.Time `json:"revoked_at,omitempty"`
	RetrievalCount  int64      `json:"retrieval_count"`
	LastRetrievedAt *time.Time `json:"last_retrieved_at,omitempty"`
	CreatedAt       time.Time  `json:"created_at"`
}

type CreateInput struct {
	SpaceID       string
	ArtifactID    string
	Filename      string
	MediaType     string
	SizeBytes     int64
	SHA256        string
	StorageKey    string
	CreatedByType string
	CreatedByID   string
	SourceType    string
	SourceID      string
	Title         string
	ExpiresAt     *time.Time
}

type CreateShareInput struct {
	ArtifactID    string
	SpaceID       string
	TokenSHA256   string
	CreatedByType string
	CreatedByID   string
	ExpiresAt     *time.Time
}

type Expired struct {
	ArtifactID string
	SpaceID    string
}

type PurgeStore interface {
	// ExpireArtifacts tombstones live artifacts whose ExpiresAt has passed,
	// at most limit of them, and reports which.
	ExpireArtifacts(ctx context.Context, now time.Time, limit int) ([]Expired, error)
	// PurgeableArtifacts returns artifacts tombstoned at or before the cutoff
	// whose objects have not been reclaimed, at most limit of them.
	PurgeableArtifacts(ctx context.Context, before time.Time, limit int) ([]Purgeable, error)
	// MarkArtifactPurged clears the storage key, recording that the object is
	// gone. It reports whether it changed anything, so two sweeps racing on one
	// artifact count it once.
	MarkArtifactPurged(ctx context.Context, artifactID string) (bool, error)
}

type Purgeable struct {
	ArtifactID string
	SpaceID    string
	SizeBytes  int64
}

type Ref struct {
	SpaceID    string
	ArtifactID string
}

type ResolvedShare struct {
	Share    ArtifactShare
	Artifact Artifact
}

type ShareStore interface {
	CreateArtifactShare(ctx context.Context, in CreateShareInput) (*ArtifactShare, error)
	// GetArtifactShareByTokenHash returns the share and its artifact by the
	// token's hash, or (nil, nil) when the token matches nothing. It does NOT
	// filter revoked, expired, or tombstoned: the caller applies liveness so a
	// public route answers every non-live case with the same 404, and a
	// management view can still show a revoked link. A tombstoned artifact is
	// returned like GetArtifact returns one.
	GetArtifactShareByTokenHash(ctx context.Context, tokenHash string) (*ResolvedShare, error)
	// ListArtifactShares returns an artifact's shares, newest first, including
	// revoked and expired ones for the management view.
	ListArtifactShares(ctx context.Context, artifactID string) ([]ArtifactShare, error)
	// RevokeArtifactShare marks a share revoked if it belongs to the artifact
	// and is not already revoked, reporting whether it changed anything so a
	// repeat revoke is distinguishable from a first.
	RevokeArtifactShare(ctx context.Context, artifactID, shareID string, revokedAt time.Time) (bool, error)
	// RecordArtifactShareRetrieval increments the count and stamps the time.
	// Best-effort telemetry: a failure must never block content delivery.
	RecordArtifactShareRetrieval(ctx context.Context, shareID string, at time.Time) error
}

type Store interface {
	CreateArtifact(ctx context.Context, in CreateInput) (*Artifact, error)
	// GetArtifact returns the artifact by its opaque ID, or (nil, nil) when there
	// is none. A tombstoned artifact is returned, not hidden: the caller has to
	// tell "never existed" from "deleted" to answer either one correctly.
	GetArtifact(ctx context.Context, artifactID string) (*Artifact, error)
	// ListArtifactsBySpace returns live artifacts newest first, with the total.
	ListArtifactsBySpace(ctx context.Context, spaceID string, limit, offset int) ([]Artifact, int, error)
	// ListArtifactsBySource returns live artifacts produced by any of the given
	// operations, newest first, keyed by source ID. It is how a work object
	// finds what its runs published without owning them.
	ListArtifactsBySource(ctx context.Context, sourceIDs []string) (map[string][]Artifact, error)
	// SoftDeleteArtifact tombstones the artifact and reports whether it changed
	// anything, so a repeat delete is distinguishable from a first one.
	SoftDeleteArtifact(ctx context.Context, artifactID string, deletedAt time.Time) (bool, error)
	// SpaceArtifactBytes sums what the space's live artifacts hold. Tombstoned
	// ones are excluded whether or not their objects have gone yet: the space
	// has given them up, and charging for storage the deployment has merely not
	// swept would make a quota depend on sweep timing.
	SpaceArtifactBytes(ctx context.Context, spaceID string) (int64, error)
}