README
¶
Artifact lifecycle
Use RetainedReader when reading optimization evidence. It combines the existing
content verifier with retention metadata, checking eligibility before the provider
read and again before returning bytes. The provider must enforce current artifact
permissions and bound its allocations. Returned creation and expiry dates must
match the registered metadata.
The final metadata read is an observation point. It does not grant a lease over the returned bytes. Decisions and activation still need the retention checks in their own database transaction.
DeletionService.Delete first checks host authority, resolves the attributed
actor and commits the deletion request. That transaction invalidates evidence and
queues dependent lesson revocations before the provider receives a delete call.
Pass an actor supplied by your authenticated host boundary. Do not accept the
subject from an agent or an unchecked request body.
The provider implements Tombstoner. It must persist a permanent tombstone,
including for an absent object, so a delayed upload cannot restore the content.
Return a DeletionReceipt only after verifying the full reference binding,
request ID, actor and reason against that stored tombstone. An object-store 404 or
an accepted delete request does not establish this proof.
Each invocation calls the provider at most once. If the result is uncertain or
the final metadata write fails, the deletion stays pending. Call Recover with
the same reference to resume it, including after reopening the database. Recovery
resolves the saved actor and checks current grants; the recovering worker does
not replace that actor. Identical provider requests must be idempotent.
Caller cancellation and deadlines survive identity resolution. Provider success followed by revocation or cancellation leaves the local deletion pending for a later authorized reconciliation. Completed retries still check authority, but do not repeat the provider operation.
Use Recovery.RunPage to discover pending deletions and expired artifacts in one
exact scope. Keep the cutoff fixed while following NextCursor. Rows are ordered
by their immutable registration time and reference binding, so completing a
deletion does not shift the remaining pages. After the last page, start another
sweep with a new cutoff and empty cursor to pick up failed work and records that
became eligible behind the previous cursor.
Configure the recovery runner with your host's retention identity. It uses that
identity for new expiry requests and resolves the saved original actor for pending
requests. Each item is reread before acting, then passes through DeletionService.
Concurrent manual deletion requests keep their actor and request identity.
A page visits at most 500 items (100 by default). Each item gets up to 30 seconds,
or a shorter timeout you configure. Providers must honor cancellation. The runner
does not launch a goroutine that abandons an ongoing provider operation. Check
every Outcomes entry: an individual failure stays pending while later items can
proceed. If RunPage returns an error, retry the same input cursor; do not advance
from a partial result.
You own scheduling, authorized scope enumeration, continuation persistence and failure reporting. The runner starts no background service. Page size bounds provider work, but the current list implementation still loads the whole scope from durable storage. Bounded database queries and throughput qualification remain open.
The built-in database content adapter and scheduled retention worker are not yet implemented. This package does not import the unreleased root evidence APIs.
Documentation
¶
Overview ¶
Package artifacts coordinates protected content with optimization retention.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DeletionMetadata ¶
type DeletionMetadata interface {
GetArtifact(context.Context, optimization.ArtifactRef) (optimization.ArtifactRetention, error)
GetExperiment(context.Context, id.ID) (optimization.Experiment, error)
Transact(context.Context, func(optimization.Transaction) error) error
}
DeletionMetadata is the transactional metadata required for deletion recovery.
type DeletionReceipt ¶
type DeletionReceipt struct {
BindingDigest string
RequestID string
Actor optimization.IdentityRef
Reason string
}
DeletionReceipt identifies a durable tombstone verified by the content adapter. A missing object or successful transport response alone is not a receipt.
type DeletionService ¶
type DeletionService struct {
// contains filtered or unexported fields
}
DeletionService invalidates evidence before attempting physical deletion. It makes one provider call per invocation. Pending requests survive crashes and can be retried through Recover with fresh grants for the saved original actor.
func NewDeletionService ¶
func NewDeletionService(metadata DeletionMetadata, provider Tombstoner, authorizer optimization.Authorizer, resolver optimization.IdentityResolver) (*DeletionService, error)
NewDeletionService requires explicit storage, provider and host authority.
func (*DeletionService) Delete ¶
func (s *DeletionService) Delete(ctx context.Context, request optimization.ArtifactDeletion) error
Delete accepts a host-attributed command. The host must bind Actor to the authenticated caller, never accept a model-supplied or untrusted subject.
func (*DeletionService) Recover ¶
func (s *DeletionService) Recover(ctx context.Context, ref optimization.ArtifactRef) error
Recover resumes only a previously saved deletion. It never creates a request or substitutes the recovering worker's identity for the original actor.
type Recovery ¶
type Recovery struct {
// contains filtered or unexported fields
}
Recovery processes a single page per call. The host owns scheduling, scope enumeration, continuation persistence and reporting failures. Providers must honor cancellation; no background goroutine is started to abandon a delete.
func NewRecovery ¶
func NewRecovery(metadata RecoveryMetadata, deletion *DeletionService, actor optimization.IdentityRef, timeout time.Duration) (*Recovery, error)
NewRecovery requires the host's retention identity for new expiry requests. Pending requests retain their saved actor. A zero timeout selects 30 seconds; an explicit per-item timeout must be positive and at most 30 seconds.
func (*Recovery) RunPage ¶
func (r *Recovery) RunPage(ctx context.Context, cutoff time.Time, query optimization.PageQuery) (RecoveryResult, error)
RunPage uses one fixed cutoff throughout a sweep. A failed call must be retried with the same input cursor; successful item operations are idempotent. A successful call may still contain individual failures. Start a fresh sweep after reaching an empty NextCursor so failed or newly eligible rows are found. Page limits bound provider calls, not the store's current snapshot hydration.
type RecoveryMetadata ¶
type RecoveryMetadata interface {
ListArtifactWork(context.Context, time.Time, optimization.PageQuery) (optimization.Page[optimization.ArtifactRetention], error)
GetArtifact(context.Context, optimization.ArtifactRef) (optimization.ArtifactRetention, error)
}
RecoveryMetadata discovers deletion work within one exact host scope.
type RecoveryOutcome ¶
type RecoveryOutcome struct {
Ref optimization.ArtifactRef
Err error
}
RecoveryOutcome records one attempted reconciliation, including its failure.
type RecoveryResult ¶
type RecoveryResult struct {
Outcomes []RecoveryOutcome
NextCursor string
}
RecoveryResult advances only a fully visited page. Individual errors remain in Outcomes and must be retried by a later sweep starting with an empty cursor.
type RetainedReader ¶
type RetainedReader struct {
// contains filtered or unexported fields
}
RetainedReader checks both durable eligibility and freshly verified content. Its final check establishes an observation point, not a lease over returned bytes. Decision commits must still use transactional retention checks.
func NewRetainedReader ¶
func NewRetainedReader(metadata RetentionReader, provider optimization.ArtifactReader, maxBytes int64, now func() time.Time) (*RetainedReader, error)
NewRetainedReader requires a provider that enforces current artifact grants. The maximum byte limit applies through the shared content verifier.
func (*RetainedReader) Get ¶
func (r *RetainedReader) Get(ctx context.Context, ref optimization.ArtifactRef) (optimization.Artifact, error)
Get refuses missing, expired or invalidated evidence, including deletion that commits while content is being fetched. Provider retention cannot override the dates registered in the metadata transaction.
type RetentionReader ¶
type RetentionReader interface {
GetArtifact(context.Context, optimization.ArtifactRef) (optimization.ArtifactRetention, error)
}
RetentionReader reads exact-scope artifact metadata without returning bytes.
type Tombstoner ¶
type Tombstoner interface {
Tombstone(context.Context, optimization.ArtifactDeletion) (DeletionReceipt, error)
}
Tombstoner must check current provider grants and persist a permanent fence against delayed uploads, including for an absent object. Identical requests are idempotent. Return a receipt only after verifying the stored tombstone's exact reference, request, actor and reason. Unknown outcomes must remain errors.
Source Files