IRollupArchiveLifecycleService

Namespace: Meshmakers.Octo.Runtime.Contracts.StreamData

Rollup-specific lifecycle operations layered on top of IArchiveLifecycleService. Status transitions (Activate / Disable / Enable / RetryActivation / Delete) go through the shared archive lifecycle service since rollups inherit those semantics unchanged (concept §2); this interface only adds the operations that are unique to rollups: freeze / unfreeze and watermark rewind. Backs the GraphQL mutations defined in concept §9.

public interface IRollupArchiveLifecycleService

Methods

CreateAsync(String, IReadOnlyList<RollupSourceReference>, TimeSpan, TimeSpan, IReadOnlyList<CkRollupAggregationSpec>, BucketAlignment, String, Nullable<TimeSpan>)

Creates a new CkRollupArchive entity in CkArchiveStatus.Created from a rollup-specific input. The inherited CkArchive attributes TargetCkTypeId (from the first source archive) and Columns (from RollupColumnGenerator.Generate(IReadOnlyList<CkRollupAggregationSpec>)) are resolved server-side so callers don't have to duplicate the column-derivation rule. Concept §4. Throws ArchiveNotFoundException if any entry of sources doesn't resolve.

Task<OctoObjectId> CreateAsync(string rtWellKnownName, IReadOnlyList<RollupSourceReference> sources, TimeSpan bucketSize, TimeSpan watermarkLag, IReadOnlyList<CkRollupAggregationSpec> aggregations, BucketAlignment bucketAlignment, string referenceTimeZone, Nullable<TimeSpan> carryLookback)

Parameters

rtWellKnownName String
Optional human-readable name. Null falls back to the rtId.

sources IReadOnlyList<RollupSourceReference>
The source archives this rollup aggregates from, each with an optional validity span (AB#5157). At least one entry is required. Persisted as declared — the deprecated single SourceArchiveRtId scalar is never written.

bucketSize TimeSpan
Bucket width.

watermarkLag TimeSpan
How long the orchestrator waits after bucket-end before aggregating.

aggregations IReadOnlyList<CkRollupAggregationSpec>
User-defined aggregation specs, logical over every source.

bucketAlignment BucketAlignment
Bucket-boundary alignment; defaults to BucketAlignment.FixedSize.

referenceTimeZone String
Optional IANA reference time zone for calendar alignments; null ⇒ UTC.

carryLookback Nullable<TimeSpan>
Optionally bounds the CkRollupFunction.TimeWeightedAvg carry-in scan (LOCF opening state); null ⇒ the engine default of 35 days. Only meaningful when the aggregations include TimeWeightedAvg. AB#4336 / decision D1.

Returns

Task<OctoObjectId>
The generated runtime id of the new rollup archive.

Remarks:

The full aggregation rules, the source-span rules and the transitive cycle check all run before the entity is inserted (AB#5157), so an invalid declaration fails fast at create time instead of only at activation.

FreezeAsync(OctoObjectId, DateTime)

Sets RollupArchiveSnapshot.FrozenUntil to until. Monotonic: rejected when until is earlier than the current value (use IRollupArchiveLifecycleService.UnfreezeAsync(OctoObjectId, Boolean) instead). When set, the orchestrator will not produce new buckets whose bucketEnd falls within the frozen range; already-aggregated rows in that range are preserved. Concept §6, §9.

Task FreezeAsync(OctoObjectId rollupRtId, DateTime until)

Parameters

rollupRtId OctoObjectId

until DateTime

Returns

Task

UnfreezeAsync(OctoObjectId, Boolean)

Clears RollupArchiveSnapshot.FrozenUntil. Rejected when source data inside the previously frozen range has been truncated and acceptGaps is false, because unfreezing would produce visible gaps once the orchestrator catches up. The override is intentional so an operator can knowingly accept the inconsistency. Concept §9.

Task UnfreezeAsync(OctoObjectId rollupRtId, bool acceptGaps)

Parameters

rollupRtId OctoObjectId

acceptGaps Boolean

Returns

Task

RewindWatermarkAsync(OctoObjectId, DateTime)

Resets RollupArchiveSnapshot.LastAggregatedBucketEnd to toBucketEnd (truncated to the bucket boundary). Subsequent orchestrator ticks re-aggregate the rewound range. Destructive: previously committed rows in that range are temporarily out of sync until the orchestrator catches up. Requires elevated permission (the GraphQL field enforces the StreamDataAdmin role). Concept §5, §9.

Task RewindWatermarkAsync(OctoObjectId rollupRtId, DateTime toBucketEnd)

Parameters

rollupRtId OctoObjectId

toBucketEnd DateTime

Returns

Task