Threadline.Evidence (Threadline v1.0.0)

Copy Markdown View Source

Threadline evidence records snapshot a subject's status and details at a point in time.

Use record_* functions to append posture snapshots. Use list_history/2 or list_subject_ref_history/4 to inspect history, list_latest_subject_refs/3 or list_overview/2 to inspect current snapshots, and get_latest_subject_ref/3 for one subject reference.

Summary

Types

export_delivery_attrs()

Caller fields for an export-delivery snapshot as a map or keyword list. See record_attrs/0 for the accepted keys.

get_latest_subject_ref_opt()

Options accepted by get_latest_subject_ref/3.

history_filter()

A history filter accepted by list_history/2.

invalid_subject_ref()

A non-map value rejected as an Evidence subject reference.

latest_filter()

A latest-snapshot filter accepted by latest-read functions.

list_history_opt()

Options accepted by list_history/2.

list_latest_subject_refs_opt()

Options accepted by list_latest_subject_refs/3.

list_overview_opt()

Options accepted by list_overview/2.

list_subject_ref_history_opt()

Options accepted by list_subject_ref_history/4.

record_attrs()

Common caller fields cast by Evidence record changesets: :summary_status, :recorded_at, :actor_ref, :provenance, :detail, and :schema_version. Threadline supplies the subject fields and defaults.

record_opt()

Options accepted by Evidence record writers.

record_result()

Result returned by an Evidence record writer.

redaction_policy_attr_key()

A top-level atom or string key in redaction-policy evidence attrs.

redaction_policy_attr_value()

Values accepted for redaction-policy evidence fields cast by the record changeset.

redaction_policy_attrs()

Caller fields accepted by the changeset: :summary_status, :recorded_at, :actor_ref, :provenance, :detail, and :schema_version. Threadline supplies :subject, :subject_ref, and defaults.

redaction_policy_attrs_input()

Redaction-policy attrs as a map or keyword list.

retention_policy_attrs()

Caller fields for a retention-policy snapshot as a map or keyword list. See record_attrs/0 for the accepted keys.

retention_run_attrs()

Caller fields for a retention-run snapshot as a map or keyword list. See record_attrs/0 for the accepted keys.

subject_ref()

A subject reference accepted by an Evidence writer. Atom keys and values are normalized to strings.

subject_ref_history_filter()

A subject-reference history filter accepted by list_subject_ref_history/4.

subject_ref_value()

A subject reference represented with atom or string keys and JSON-compatible values.

support_scope_posture_attrs()

Caller fields for a support-scope snapshot as a map or keyword list. See record_attrs/0 for the accepted keys.

trigger_coverage_attrs()

Caller fields for a trigger-coverage snapshot as a map or keyword list. See record_attrs/0 for the accepted keys.

Functions

get_latest_subject_ref(subject, subject_ref, opts)

Returns the newest EvidenceRecord for one subject and subject reference, or nil when none exists.

list_history(filters, opts \\ [])

Returns matching EvidenceRecord snapshots ordered newest first by recorded time and ID.

list_latest_subject_refs(subject, filters \\ [], opts)

Returns the newest EvidenceRecord for each reference in one subject family, newest first.

list_overview(filters, opts \\ [])

Returns the newest EvidenceRecord for each subject reference across all supported subjects, newest first.

list_subject_ref_history(subject, subject_ref, filters \\ [], opts)

Returns EvidenceRecord snapshots for one subject and subject reference, newest first by recorded time and ID.

record_export_delivery(subject_ref, attrs, opts \\ [])

Records an export-delivery evidence snapshot for subject_ref and returns {:ok, record} after persistence.

record_redaction_policy(subject_ref, attrs, opts \\ [])

Records a redaction-policy evidence snapshot for subject_ref and returns {:ok, record} after persistence.

record_retention_policy(subject_ref, attrs, opts \\ [])

Records a retention-policy evidence snapshot for subject_ref and returns {:ok, record} after persistence.

record_retention_run(subject_ref, attrs, opts \\ [])

Records a retention-run evidence snapshot for subject_ref and returns {:ok, record} after persistence.

record_support_scope_posture(subject_ref, attrs, opts \\ [])

Records a support-scope evidence snapshot for subject_ref and returns {:ok, record} after persistence.

record_trigger_coverage(subject_ref, attrs, opts \\ [])

Records a trigger-coverage evidence snapshot for subject_ref and returns {:ok, record} after persistence.

Types

export_delivery_attrs()

@type export_delivery_attrs() ::
  record_attrs()
  | [{redaction_policy_attr_key(), redaction_policy_attr_value()}]

Caller fields for an export-delivery snapshot as a map or keyword list. See record_attrs/0 for the accepted keys.

get_latest_subject_ref_opt()

@type get_latest_subject_ref_opt() :: record_opt()

Options accepted by get_latest_subject_ref/3.

history_filter()

@type history_filter() ::
  Threadline.repo_opt()
  | {:subject, Threadline.Evidence.Subject.subject_descriptor()}
  | {:subject_ref, subject_ref()}
  | {:from, DateTime.t()}
  | {:to, DateTime.t()}
  | {:limit, pos_integer()}

A history filter accepted by list_history/2.

invalid_subject_ref()

@type invalid_subject_ref() ::
  atom()
  | bitstring()
  | number()
  | tuple()
  | list()
  | pid()
  | port()
  | reference()
  | function()

A non-map value rejected as an Evidence subject reference.

latest_filter()

@type latest_filter() ::
  Threadline.repo_opt()
  | {:from, DateTime.t()}
  | {:to, DateTime.t()}
  | {:limit, pos_integer()}

A latest-snapshot filter accepted by latest-read functions.

list_history_opt()

@type list_history_opt() :: record_opt()

Options accepted by list_history/2.

list_latest_subject_refs_opt()

@type list_latest_subject_refs_opt() :: record_opt()

Options accepted by list_latest_subject_refs/3.

list_overview_opt()

@type list_overview_opt() :: record_opt()

Options accepted by list_overview/2.

list_subject_ref_history_opt()

@type list_subject_ref_history_opt() :: record_opt()

Options accepted by list_subject_ref_history/4.

record_attrs()

@type record_attrs() :: redaction_policy_attrs()

Common caller fields cast by Evidence record changesets: :summary_status, :recorded_at, :actor_ref, :provenance, :detail, and :schema_version. Threadline supplies the subject fields and defaults.

record_opt()

@type record_opt() :: Threadline.repo_opt() | Threadline.storage_schema_opt()

Options accepted by Evidence record writers.

record_result()

@type record_result() ::
  {:ok, Threadline.Governance.EvidenceRecord.t()}
  | {:error, Ecto.Changeset.t()}
  | {:error, :missing_repo}
  | {:error, {:invalid_subject_ref, invalid_subject_ref()}}

Result returned by an Evidence record writer.

redaction_policy_attr_key()

@type redaction_policy_attr_key() :: atom() | String.t()

A top-level atom or string key in redaction-policy evidence attrs.

redaction_policy_attr_value()

@type redaction_policy_attr_value() ::
  String.t()
  | DateTime.t()
  | NaiveDateTime.t()
  | Threadline.Semantics.ActorRef.t()
  | subject_ref()
  | pos_integer()
  | nil

Values accepted for redaction-policy evidence fields cast by the record changeset.

redaction_policy_attrs()

@type redaction_policy_attrs() :: %{
  optional(atom() | String.t()) => redaction_policy_attr_value()
}

Caller fields accepted by the changeset: :summary_status, :recorded_at, :actor_ref, :provenance, :detail, and :schema_version. Threadline supplies :subject, :subject_ref, and defaults.

redaction_policy_attrs_input()

@type redaction_policy_attrs_input() ::
  redaction_policy_attrs()
  | [{redaction_policy_attr_key(), redaction_policy_attr_value()}]

Redaction-policy attrs as a map or keyword list.

retention_policy_attrs()

@type retention_policy_attrs() ::
  record_attrs()
  | [{redaction_policy_attr_key(), redaction_policy_attr_value()}]

Caller fields for a retention-policy snapshot as a map or keyword list. See record_attrs/0 for the accepted keys.

retention_run_attrs()

@type retention_run_attrs() ::
  record_attrs()
  | [{redaction_policy_attr_key(), redaction_policy_attr_value()}]

Caller fields for a retention-run snapshot as a map or keyword list. See record_attrs/0 for the accepted keys.

subject_ref()

@type subject_ref() :: %{optional(atom() | String.t()) => subject_ref_value()}

A subject reference accepted by an Evidence writer. Atom keys and values are normalized to strings.

subject_ref_history_filter()

@type subject_ref_history_filter() ::
  Threadline.repo_opt()
  | {:from, DateTime.t()}
  | {:to, DateTime.t()}
  | {:limit, pos_integer()}

A subject-reference history filter accepted by list_subject_ref_history/4.

subject_ref_value()

@type subject_ref_value() ::
  Threadline.json_value()
  | atom()
  | %{optional(atom() | String.t()) => subject_ref_value()}

A subject reference represented with atom or string keys and JSON-compatible values.

support_scope_posture_attrs()

@type support_scope_posture_attrs() ::
  record_attrs()
  | [{redaction_policy_attr_key(), redaction_policy_attr_value()}]

Caller fields for a support-scope snapshot as a map or keyword list. See record_attrs/0 for the accepted keys.

trigger_coverage_attrs()

@type trigger_coverage_attrs() ::
  record_attrs()
  | [{redaction_policy_attr_key(), redaction_policy_attr_value()}]

Caller fields for a trigger-coverage snapshot as a map or keyword list. See record_attrs/0 for the accepted keys.

Functions

get_latest_subject_ref(subject, subject_ref, opts)

@spec get_latest_subject_ref(
  Threadline.Evidence.Subject.subject_descriptor(),
  subject_ref(),
  [get_latest_subject_ref_opt()]
) :: Threadline.Governance.EvidenceRecord.t() | nil

Returns the newest EvidenceRecord for one subject and subject reference, or nil when none exists.

Use list_subject_ref_history/4 when every snapshot for the reference is needed. This lookup uses the full subject reference and does not apply date bounds or a result limit.

Options

  • :repo — Ecto repository module. Required.
  • :storage_schema — string storage schema override. Optional.

Returns

Returns the newest %Threadline.Governance.EvidenceRecord{} or nil when no row matches. Raises ArgumentError for an unsupported subject, an invalid subject reference, a missing repository, or an invalid storage schema.

list_history(filters, opts \\ [])

@spec list_history([history_filter()], [list_history_opt()]) :: [
  Threadline.Governance.EvidenceRecord.t()
]

Returns matching EvidenceRecord snapshots ordered newest first by recorded time and ID.

Use list_subject_ref_history/4 to read one subject reference's history. This function can combine multiple subjects and references; :from and :to are inclusive, and :limit caps the returned list.

Filters

  • :repo — Ecto repository module. Optional when supplied in options.
  • :subject — supported subject name, atom, or descriptor. Optional.
  • :subject_ref — subject reference map. Optional.
  • :from — DateTime. Optional; inclusive lower bound on recorded_at.
  • :to — DateTime. Optional; inclusive upper bound on recorded_at.
  • :limit — positive integer. Optional; caps the result list.

Unknown keys raise ArgumentError naming the allowed keys.

Options

  • :repo — Ecto repository module. Required in filters or options; the option takes precedence.
  • :storage_schema — string storage schema override. Optional.

Returns

Returns a list of %Threadline.Governance.EvidenceRecord{} rows, including an empty list when no records match. Raises ArgumentError for invalid filters, a missing repository, or an invalid storage schema.

list_latest_subject_refs(subject, filters \\ [], opts)

@spec list_latest_subject_refs(
  Threadline.Evidence.Subject.subject_descriptor(),
  [latest_filter()],
  [
    list_latest_subject_refs_opt()
  ]
) :: [Threadline.Governance.EvidenceRecord.t()]

Returns the newest EvidenceRecord for each reference in one subject family, newest first.

Use list_history/2 to inspect every snapshot in the family. The date bounds apply before the newest row per reference is selected.

Filters

  • :repo — Ecto repository module. Optional when supplied in options.
  • :from — DateTime. Optional; inclusive lower bound on recorded_at.
  • :to — DateTime. Optional; inclusive upper bound on recorded_at.
  • :limit — positive integer. Optional; caps the result list.

Unknown keys raise ArgumentError naming the allowed keys.

Options

  • :repo — Ecto repository module. Required in filters or options; the option takes precedence.
  • :storage_schema — string storage schema override. Optional.

Returns

Returns a list with at most one row per subject reference, or an empty list when no records match. Raises ArgumentError for an unsupported subject, an invalid filter, a missing repository, or an invalid storage schema.

list_overview(filters, opts \\ [])

@spec list_overview([latest_filter()], [list_overview_opt()]) :: [
  Threadline.Governance.EvidenceRecord.t()
]

Returns the newest EvidenceRecord for each subject reference across all supported subjects, newest first.

Use list_latest_subject_refs/3 when the read should cover one subject family. Inclusive date bounds apply before each latest row is selected.

Filters

  • :repo — Ecto repository module. Optional when supplied in options.
  • :from — DateTime. Optional; inclusive lower bound on recorded_at.
  • :to — DateTime. Optional; inclusive upper bound on recorded_at.
  • :limit — positive integer. Optional; caps the combined result list.

Unknown keys raise ArgumentError naming the allowed keys.

Options

  • :repo — Ecto repository module. Required in filters or options; the option takes precedence.
  • :storage_schema — string storage schema override. Optional.

Returns

Returns a list with at most one row per subject reference, or an empty list when no records match. Raises ArgumentError for an invalid filter, a missing repository, or an invalid storage schema.

list_subject_ref_history(subject, subject_ref, filters \\ [], opts)

@spec list_subject_ref_history(
  Threadline.Evidence.Subject.subject_descriptor(),
  subject_ref(),
  [subject_ref_history_filter()],
  [list_subject_ref_history_opt()]
) :: [Threadline.Governance.EvidenceRecord.t()]

Returns EvidenceRecord snapshots for one subject and subject reference, newest first by recorded time and ID.

Use list_history/2 to combine multiple subjects or references. The supplied filters add inclusive time bounds and a result limit to the fixed subject and reference.

Filters

  • :repo — Ecto repository module. Optional when supplied in options.
  • :from — DateTime. Optional; inclusive lower bound on recorded_at.
  • :to — DateTime. Optional; inclusive upper bound on recorded_at.
  • :limit — positive integer. Optional; caps the result list.

Unknown keys raise ArgumentError naming the allowed keys.

Options

  • :repo — Ecto repository module. Required in filters or options; the option takes precedence.
  • :storage_schema — string storage schema override. Optional.

Returns

Returns a list of matching %Threadline.Governance.EvidenceRecord{} rows, including an empty list when none match. Raises ArgumentError for an unsupported subject, invalid subject reference or filter, a missing repository, or an invalid storage schema.

record_export_delivery(subject_ref, attrs, opts \\ [])

@spec record_export_delivery(subject_ref(), export_delivery_attrs(), [record_opt()]) ::
  record_result()

Records an export-delivery evidence snapshot for subject_ref and returns {:ok, record} after persistence.

Evidence records are append-only snapshots. The caller supplies the delivery status and optional actor, source context, and details.

Options

  • :repo — Ecto repository module. Required.
  • :storage_schema — string storage schema override. Optional.

Returns

Returns {:ok, record} when persisted, {:error, changeset} when record validation fails, {:error, :missing_repo} when :repo is omitted, or {:error, {:invalid_subject_ref, value}} when subject_ref is not a map. Raises ArgumentError for an invalid storage schema.

record_redaction_policy(subject_ref, attrs, opts \\ [])

@spec record_redaction_policy(subject_ref(), redaction_policy_attrs_input(), [
  record_opt()
]) ::
  record_result()

Records a redaction-policy evidence snapshot for subject_ref and returns {:ok, record} after persistence.

Evidence records are append-only snapshots. The caller supplies the policy status and optional actor, source context, and details.

Options

  • :repo — the Ecto repository used to persist the record (required).
  • :storage_schema — string storage schema override.

Returns

Returns {:ok, %Threadline.Governance.EvidenceRecord{}} when persisted, {:error, changeset} when record validation fails, {:error, :missing_repo} when :repo is omitted, or {:error, {:invalid_subject_ref, value}} when subject_ref is not a map. Raises ArgumentError for an invalid storage schema.

record_retention_policy(subject_ref, attrs, opts \\ [])

@spec record_retention_policy(subject_ref(), retention_policy_attrs(), [record_opt()]) ::
  record_result()

Records a retention-policy evidence snapshot for subject_ref and returns {:ok, record} after persistence.

Evidence records are append-only snapshots. The caller supplies the policy status and optional actor, source context, and details.

Options

  • :repo — Ecto repository module. Required.
  • :storage_schema — string storage schema override. Optional.

Returns

Returns {:ok, record} when persisted, {:error, changeset} when record validation fails, {:error, :missing_repo} when :repo is omitted, or {:error, {:invalid_subject_ref, value}} when subject_ref is not a map. Raises ArgumentError for an invalid storage schema.

record_retention_run(subject_ref, attrs, opts \\ [])

@spec record_retention_run(subject_ref(), retention_run_attrs(), [record_opt()]) ::
  record_result()

Records a retention-run evidence snapshot for subject_ref and returns {:ok, record} after persistence.

Evidence records are append-only snapshots. The caller supplies the run status and optional actor, source context, and details.

Options

  • :repo — Ecto repository module. Required.
  • :storage_schema — string storage schema override. Optional.

Returns

Returns {:ok, record} when persisted, {:error, changeset} when record validation fails, {:error, :missing_repo} when :repo is omitted, or {:error, {:invalid_subject_ref, value}} when subject_ref is not a map. Raises ArgumentError for an invalid storage schema.

record_support_scope_posture(subject_ref, attrs, opts \\ [])

@spec record_support_scope_posture(subject_ref(), support_scope_posture_attrs(), [
  record_opt()
]) ::
  record_result()

Records a support-scope evidence snapshot for subject_ref and returns {:ok, record} after persistence.

Evidence records are append-only snapshots. The caller supplies the scope status and optional actor, source context, and details.

Options

  • :repo — Ecto repository module. Required.
  • :storage_schema — string storage schema override. Optional.

Returns

Returns {:ok, record} when persisted, {:error, changeset} when record validation fails, {:error, :missing_repo} when :repo is omitted, or {:error, {:invalid_subject_ref, value}} when subject_ref is not a map. Raises ArgumentError for an invalid storage schema.

record_trigger_coverage(subject_ref, attrs, opts \\ [])

@spec record_trigger_coverage(subject_ref(), trigger_coverage_attrs(), [record_opt()]) ::
  record_result()

Records a trigger-coverage evidence snapshot for subject_ref and returns {:ok, record} after persistence.

Evidence records are append-only snapshots. The caller supplies the coverage status and optional actor, source context, and details.

Options

  • :repo — Ecto repository module. Required.
  • :storage_schema — string storage schema override. Optional.

Returns

Returns {:ok, record} when persisted, {:error, changeset} when record validation fails, {:error, :missing_repo} when :repo is omitted, or {:error, {:invalid_subject_ref, value}} when subject_ref is not a map. Raises ArgumentError for an invalid storage schema.