stormlog.run_catalog

Stable public facade for run envelope and attachment catalog helpers.

class stormlog.run_catalog.CatalogRunAttachment(title, kind, storage, attachment_id, url, path, run_id, session_id, job_id, rank, local_rank, world_size, start_ns, end_ns, created_at_utc, updated_at_utc, source_namespace, source_ref, metadata=<factory>)[source]

Bases: object

Attachment declared by a run envelope.

Parameters:

title (str)
kind (str)
storage (Literal['reference', 'copy'])
attachment_id (str | None)
url (str | None)
path (str | None)
run_id (str | None)
session_id (str | None)
job_id (str | None)
rank (int | None)
local_rank (int | None)
world_size (int | None)
start_ns (int | None)
end_ns (int | None)
created_at_utc (str | None)
updated_at_utc (str | None)
source_namespace (str | None)
source_ref (str | None)
metadata (Mapping[str, Any])

title: str

kind: str

storage: Literal['reference', 'copy']

attachment_id: str | None

url: str | None

path: str | None

run_id: str | None

session_id: str | None

job_id: str | None

rank: int | None

local_rank: int | None

world_size: int | None

start_ns: int | None

end_ns: int | None

created_at_utc: str | None

updated_at_utc: str | None

source_namespace: str | None

source_ref: str | None

metadata: Mapping[str, Any]

as_dict()[source]

Return type:: dict[str, Any]

class stormlog.run_catalog.CatalogRunSessionRef(session_id, job_id, rank, local_rank, world_size, role, source_namespace, source_ref, metadata=<factory>)[source]

Bases: object

Session membership declared by a run envelope.

Parameters:

session_id (str)
job_id (str | None)
rank (int | None)
local_rank (int | None)
world_size (int | None)
role (str | None)
source_namespace (str | None)
source_ref (str | None)
metadata (Mapping[str, Any])

session_id: str

job_id: str | None

rank: int | None

local_rank: int | None

world_size: int | None

role: str | None

source_namespace: str | None

source_ref: str | None

metadata: Mapping[str, Any]

as_dict()[source]

Return type:: dict[str, Any]

class stormlog.run_catalog.RunContext(run_id, explicit, title, description, job_id, started_at_ns, ended_at_ns, source_path, source_kind, source_namespace, source_ref, sessions, tags=(), metadata=<factory>)[source]

Bases: object

Internal normalized run context used to project rows.

Parameters:

run_id (str)
explicit (bool)
title (str | None)
description (str | None)
job_id (str | None)
started_at_ns (int | None)
ended_at_ns (int | None)
source_path (str)
source_kind (str)
source_namespace (str | None)
source_ref (str | None)
sessions (tuple[SessionRowLike, ...])
tags (tuple[str, ...])
metadata (Mapping[str, Any])

run_id: str

explicit: bool

title: str | None

description: str | None

job_id: str | None

started_at_ns: int | None

ended_at_ns: int | None

source_path: str

source_kind: str

source_namespace: str | None

source_ref: str | None

sessions: tuple[SessionRowLike, ...]

tags: tuple[str, ...] = ()

metadata: Mapping[str, Any]

to_row(attachment_count)[source]

Parameters:: attachment_count (int)
Return type:: RunRow

class stormlog.run_catalog.RunIdentityConflict(identity_kind, identity_value, run_ids)[source]

Bases: object

Ambiguous identity mapping across multiple run contexts.

Parameters:

identity_kind (str)
identity_value (str)
run_ids (tuple[str, ...])

identity_kind: str

identity_value: str

run_ids: tuple[str, ...]

property message: str

class stormlog.run_catalog.RunIdentityIndex(session_to_run, job_to_run, source_ref_to_run, conflicts)[source]

Bases: object

Resolved run identity indexes plus ambiguity diagnostics.

Parameters:

session_to_run (Mapping[str, str])
job_to_run (Mapping[str, str])
source_ref_to_run (Mapping[tuple[str, str], str])
conflicts (tuple[RunIdentityConflict, ...])

session_to_run: Mapping[str, str]

job_to_run: Mapping[str, str]

source_ref_to_run: Mapping[tuple[str, str], str]

conflicts: tuple[RunIdentityConflict, ...]

stormlog.run_catalog.attachment_storage_or_default(value)[source]

Parse an attachment storage value, defaulting legacy sidecars.

Parameters:: value (Any)
Return type:: Literal[‘reference’, ‘copy’]

stormlog.run_catalog.attachment_storage_or_none(value)[source]

Parse an attachment storage value.

Parameters:: value (Any)
Return type:: Literal[‘reference’, ‘copy’] | None

stormlog.run_catalog.build_identity_index(contexts)[source]

Build unambiguous identity maps for attachment projection.

Parameters:: contexts (Mapping[str, RunContext])
Return type:: RunIdentityIndex

stormlog.run_catalog.build_run_contexts(sessions, envelopes)[source]

Build explicit contexts plus implicit contexts for uncovered sessions.

Parameters:

sessions (Sequence[SessionRowLike])
envelopes (Sequence[CatalogRunEnvelope])

Return type:

dict[str, RunContext]

stormlog.run_catalog.diagnose_attachment_rows(source, summary, identity_index)[source]

Project a diagnose bundle into a run attachment row.

Parameters:

source (CatalogSourceLike)
summary (SessionSummary | None)
identity_index (RunIdentityIndex)

Return type:

list[RunAttachmentRow]

stormlog.run_catalog.envelope_attachment_rows(envelopes, contexts)[source]

Project explicit envelope attachments into run attachment rows.

Parameters:

envelopes (Sequence[CatalogRunEnvelope])
contexts (Mapping[str, RunContext])

Return type:

list[RunAttachmentRow]

stormlog.run_catalog.flat_telemetry_attachment_rows(source, contexts)[source]

Project flat telemetry files into run attachment rows.

Parameters:

source (CatalogSourceLike)
contexts (Mapping[str, RunContext])

Return type:

list[RunAttachmentRow]

stormlog.run_catalog.is_run_envelope(payload)[source]

Return whether a payload advertises the exact run envelope v1 format.

Parameters:: payload (Mapping[str, Any])
Return type:: bool

stormlog.run_catalog.local_attachment_row(*, run_id, title, kind, path, session_id, job_id, rank, local_rank, world_size, start_ns, end_ns, source_kind, metadata)[source]

Build a copied local artifact attachment row.

Parameters:

run_id (str)
title (str)
kind (str)
path (str)
session_id (str | None)
job_id (str | None)
rank (int | None)
local_rank (int | None)
world_size (int | None)
start_ns (int | None)
end_ns (int | None)
source_kind (str)
metadata (Mapping[str, Any])

Return type:

RunAttachmentRow

stormlog.run_catalog.oom_attachment_rows(bundles, identity_index, session_by_id)[source]

Project OOM bundles into run attachment rows with session metadata.

Parameters:

bundles (Sequence[OOMBundleLike])
identity_index (RunIdentityIndex)
session_by_id (Mapping[str, SessionRowLike])

Return type:

list[RunAttachmentRow]

stormlog.run_catalog.rollup_attachment_rows(source, manifest, identity_index)[source]

Project sink rollup sidecars into run attachment rows.

Parameters:

source (CatalogSourceLike)
manifest (TelemetrySinkManifest)
identity_index (RunIdentityIndex)

Return type:

list[RunAttachmentRow]

stormlog.run_catalog.run_attachment_matches(row, filters)[source]

Return whether an attachment row satisfies filters.

Parameters:

row (RunAttachmentRow)
filters (RunAttachmentFilter)

Return type:

bool

stormlog.run_catalog.run_envelope_from_payload(payload, envelope_path)[source]

Parse a run envelope only when the complete v1 schema is satisfied.

Parameters:

payload (Mapping[str, Any])
envelope_path (Path)

Return type:

CatalogRunEnvelope | None

stormlog.run_catalog.run_id_for_identity(*, run_id, session_id, job_id, source_namespace, source_ref, identity_index)[source]

Resolve an attachment run id without using ambiguous identities.

Parameters:

run_id (str | None)
session_id (str | None)
job_id (str | None)
source_namespace (str | None)
source_ref (str | None)
identity_index (RunIdentityIndex)

Return type:

str | None

stormlog.run_catalog.run_matches(row, filters)[source]

Return whether a run row satisfies filters.

Parameters:

row (RunRow)
filters (RunFilter)

Return type:

bool

stormlog.run_catalog.sidecar_attachment_rows(attachments, identity_index)[source]

Project external sidecar attachments into run attachment rows.

Parameters:

attachments (Sequence[ExternalAttachment])
identity_index (RunIdentityIndex)

Return type:

list[RunAttachmentRow]

stormlog.run_catalog.sink_attachment_rows(source, manifest, identity_index)[source]

Project sink directory and segment rows for all mapped sessions.

Parameters:

source (CatalogSourceLike)
manifest (TelemetrySinkManifest)
identity_index (RunIdentityIndex)

Return type:

list[RunAttachmentRow]

stormlog.run_catalog.sink_segment_attachment_rows(source, manifest, identity_index)[source]

Project sink segment files into run attachment rows.

Parameters:

source (CatalogSourceLike)
manifest (TelemetrySinkManifest)
identity_index (RunIdentityIndex)

Return type:

list[RunAttachmentRow]