idiolect-records 0.4.1

// @generated by idiolect-codegen. do not edit.
// source: dev.idiolect.defs

//! Shared types for the dev.idiolect.* Lexicon family. Covers (a) cross-cutting reference shapes (lens/schema/encounter refs, tool identity, visibility), and (b) content-theory types (purpose, lensProperty, evidence, caveat) shared across multiple records. Record-specific combinator trees (condition, eligibility, constraint, convention) live in their respective record lexicons.

#![allow(
    missing_docs,
    clippy::doc_markdown,
    clippy::struct_excessive_bools,
    clippy::derive_partial_eq_without_eq
)]
use serde::{Deserialize, Serialize};

/// Structured grounding for an attitudinal claim: what the holder's assertion/endorsement/belief rests on. Useful when the record's author is not the holder (third-party attestation) or when the grounds are externally anchored.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "$type")]
pub enum Basis {
    #[serde(rename = "dev.idiolect.defs#basisSelfAsserted")]
    BasisSelfAsserted(BasisSelfAsserted),
    #[serde(rename = "dev.idiolect.defs#basisCommunityPolicy")]
    BasisCommunityPolicy(BasisCommunityPolicy),
    #[serde(rename = "dev.idiolect.defs#basisExternalSignal")]
    BasisExternalSignal(BasisExternalSignal),
    #[serde(rename = "dev.idiolect.defs#basisDerivedFromRecord")]
    BasisDerivedFromRecord(BasisDerivedFromRecord),
}

/// Grounded in a community's published policy. `community` is the community record; `policyUri` optionally names the specific policy document.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct BasisCommunityPolicy {
    /// AT-URI of the community record whose policy grounds this record.
    pub community: idiolect_records::AtUri,
    /// Optional pointer to the specific policy document.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub policy_uri: Option<idiolect_records::Uri>,
}

/// Grounded in another record on ATProto. `source` pins the exact version via strong ref; `inferenceRule` names how this record derives from it (e.g. 'translates', 'aggregates', 'classifies').
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct BasisDerivedFromRecord {
    /// Identifier of the inference rule (e.g. 'classifier:purpose-v1', 'lens:v1-to-v2', 'aggregation:byte-mean').
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub inference_rule: Option<String>,
    /// Strong reference (AT-URI + CID) to the record this claim is derived from.
    pub source: StrongRecordRef,
}

/// Grounded in something outside ATProto — a public license, an external policy, a standards document, a statement on another network.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct BasisExternalSignal {
    /// Optional narrative of how the signal grounds the claim.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    /// Short identifier for the signal kind (e.g. 'license:CC-BY-NC-4.0', 'robots.txt', 'policy:iso-8601').
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub signal_type: Option<String>,
    /// Pointer to the external signal.
    pub url: idiolect_records::Uri,
}

/// The holder is asserting directly, with no external grounding claimed. This is the default when a record carries no `basis`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct BasisSelfAsserted {}

/// Structured caveat on a recommendation: a known failure mode consumers can match on. Paired with `caveatsText` on the record for narrative context.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Caveat {
    /// Dotted paths or field names the caveat applies to.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub affects: Option<Vec<String>>,
    /// Short failure-mode identifier (e.g. 'loses-dialect-markers', 'degrades-on-long-inputs', 'requires-closed-world').
    pub mode: String,
    /// Advisory severity.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub severity: Option<CaveatSeverity>,
}

/// Reference to a prior encounter record. at-uri is canonical; cid pins the exact revision.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct EncounterRef {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cid: Option<String>,
    pub uri: idiolect_records::AtUri,
}

/// Structured evidence for a retrospection finding. Complements the narrative `detail` field on finding; kind=other may omit evidence entirely.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "$type")]
pub enum Evidence {
    #[serde(rename = "dev.idiolect.defs#evidenceDivergence")]
    EvidenceDivergence(EvidenceDivergence),
    #[serde(rename = "dev.idiolect.defs#evidenceLoss")]
    EvidenceLoss(EvidenceLoss),
    #[serde(rename = "dev.idiolect.defs#evidenceMismatch")]
    EvidenceMismatch(EvidenceMismatch),
}

/// For kind=merge-divergence: two translation paths that should have converged but produced different outputs.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct EvidenceDivergence {
    /// Sequence of lenses composed in path A.
    pub path_a: Vec<LensRef>,
    /// Sequence of lenses composed in path B.
    pub path_b: Vec<LensRef>,
    /// Optional cid of an input where the two paths diverge.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub witness_input: Option<String>,
}

/// For kind=data-loss: a source-schema field unrepresented in the target after translation.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct EvidenceLoss {
    /// Dotted path into the source schema identifying the lost field.
    pub source_field: String,
    /// Target schema under which the loss was observed.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub target_schema: Option<SchemaRef>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub witness_input: Option<String>,
}

/// For kind=reconciliation-mismatch: two records that should reconcile under the lens but do not.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct EvidenceMismatch {
    /// Dotted path or projection under which equality was expected.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub expected_equality_on: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub left_record: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub right_record: Option<String>,
}

/// What a verification actually asserts. Each verification kind has its own statement shape. Consumers (proof checkers, PBT runners, conformance runners) dispatch on the tagged variant.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "$type")]
pub enum LensProperty {
    #[serde(rename = "dev.idiolect.defs#lpRoundtrip")]
    LpRoundtrip(LpRoundtrip),
    #[serde(rename = "dev.idiolect.defs#lpGenerator")]
    LpGenerator(LpGenerator),
    #[serde(rename = "dev.idiolect.defs#lpTheorem")]
    LpTheorem(LpTheorem),
    #[serde(rename = "dev.idiolect.defs#lpConformance")]
    LpConformance(LpConformance),
    #[serde(rename = "dev.idiolect.defs#lpChecker")]
    LpChecker(LpChecker),
    #[serde(rename = "dev.idiolect.defs#lpConvergence")]
    LpConvergence(LpConvergence),
    #[serde(rename = "dev.idiolect.defs#lpCoercionLaw")]
    LpCoercionLaw(LpCoercionLaw),
}

/// Reference to a lens (translation). Either an at-uri or a content-addressed hash; at least one must be present.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct LensRef {
    /// Content-addressed hash of the lens.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cid: Option<String>,
    /// Whether the lens is invertible.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub direction: Option<LensRefDirection>,
    /// AT-URI pointing to a lens record.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uri: Option<idiolect_records::AtUri>,
}

/// Static-check configuration: which checker and which ruleset the verification covers.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct LpChecker {
    /// Static-checker identifier (e.g. 'panproto-check', 'clippy', 'tsc-strict').
    pub checker: String,
    /// Named ruleset, configuration preset, or lint family.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ruleset: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub version: Option<String>,
}

/// Coercion-law claim: every theory inhabitant the lens carries across a translation must satisfy the named standard's coercion laws (e.g. signature preservation, axiom soundness). Surfaced from panproto's verifyCoercionLaws xrpc; violations turn the verification falsified.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct LpCoercionLaw {
    /// Identifier of the coercion-law standard the lens is being checked against.
    pub standard: String,
    /// Optional version of the standard, useful when a standard evolves and the verification pins to a specific revision.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub version: Option<String>,
    /// Optional cap on the number of violations a runner may report before falsifying the claim. Acts as a runtime parameter, not a property assertion.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub violation_threshold: Option<i64>,
}

/// Conformance standard identifier. A conformance runner matches on name + version, optionally narrowed to named clauses.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct LpConformance {
    /// Optional subset of the standard's clauses the verification covers.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub clauses: Option<Vec<String>>,
    /// Standard name or identifier, e.g. 'iso-8601', 'rfc-3339', 'en-pos-v2.1'.
    pub standard: String,
    pub version: String,
}

/// Convergence claim: a property preserved under repeated application of the lens, appropriate for fixed-point or reconciliation lenses.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct LpConvergence {
    /// Optional bound on steps to reach fixpoint.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub bound_steps: Option<i64>,
    /// Symbolic name or description of the preserved property.
    pub property: String,
}

/// Property-based test generator spec: what the PBT runner should sample.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct LpGenerator {
    /// Name of the PBT runtime (e.g. 'proptest', 'hypothesis', 'quickcheck').
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub runner: Option<String>,
    /// Optional seed for reproducibility.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub seed: Option<i64>,
    /// Generator specification. Format is generator-runner-specific; may be a proptest Strategy reference, a Hypothesis strategy, or a QuickCheck Arbitrary.
    pub spec: String,
}

/// Roundtrip domain: the input set across which lens ∘ unlens is claimed to be the identity.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct LpRoundtrip {
    /// Symbolic description of the input set (e.g. 'all valid UD-2.14 sentences', 'records with lengths ≤ 1024').
    pub domain: String,
    /// Optional pointer to a generator that enumerates the domain.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub generator: Option<idiolect_records::Uri>,
}

/// Formal theorem statement: the property expressed in a proof-assistant vocabulary.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct LpTheorem {
    /// Names of free variables the statement quantifies over.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub free_variables: Option<Vec<String>>,
    /// The theorem statement, verbatim, in the declared `system` syntax.
    pub statement: String,
    /// Proof system (e.g. 'coq', 'lean4', 'agda', 'tlaplus', 'z3').
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub system: Option<String>,
}

/// Description of the material a purpose operates on. scope is a community-defined tag; uri optionally pins a specific corpus or dataset.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MaterialSpec {
    /// Community-defined material scope (e.g. 'classroom_materials', 'production_logs', 'scraped_corpus').
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub scope: Option<String>,
    /// Optional pointer to the specific dataset or corpus.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uri: Option<idiolect_records::Uri>,
}

/// Reference to a schema. Either an at-uri pointing to a schema record or a content-addressed hash; at least one must be present.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SchemaRef {
    /// Content-addressed hash of the schema, when tracked in a content-addressed store such as panproto-vcs.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cid: Option<String>,
    /// Schema language identifier, e.g. 'atproto-lexicon', 'postgres-sql', 'protobuf', 'graphql', 'json-schema'.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub language: Option<String>,
    /// AT-URI pointing to a schema record, when addressable via atproto.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uri: Option<idiolect_records::AtUri>,
}

/// Strong reference to an ATProto record: AT-URI plus CID. Parallel to com.atproto.repo.strongRef but repeated here so the defs tree is self-contained.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct StrongRecordRef {
    pub cid: String,
    pub uri: idiolect_records::AtUri,
}

/// Identity and version of a tool used by a verifier or observer.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Tool {
    /// Optional source commit or build identifier.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub commit: Option<String>,
    /// Canonical tool name, e.g. 'panproto', 'coq', 'tlaplus', 'z3', 'nextest'.
    pub name: String,
    /// Tool version string (semver when applicable).
    pub version: String,
}

/// Compound 'what was done, on what material, for what end, by which actor.' ThUse content-theory shape, reused across records whose structured subject is an action performed, desired, endorsed, or prohibited.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Use {
    /// Action identifier, resolved against `actionVocabulary` (or the implicit default when omitted). Examples: 'train_model', 'annotate', 'archive'.
    pub action: String,
    /// Vocabulary the `action` identifier resolves against. Omit to use a consumer-chosen default.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub action_vocabulary: Option<VocabRef>,
    /// Who ultimately performs or benefits from the action. Examples: 'researchers', 'students', 'production_users'.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub actor: Option<String>,
    /// What is being acted on.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub material: Option<MaterialSpec>,
    /// The end the action serves, resolved against `purposeVocabulary` when present. Examples: 'commercial', 'non_commercial', 'academic', 'any_purpose'.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub purpose: Option<String>,
    /// Vocabulary the `purpose` identifier resolves against. Omit to use a consumer-chosen default.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub purpose_vocabulary: Option<VocabRef>,
}

/// Visibility scope for a record. community-scoped semantics are reserved but deferred for v1; records with visibility=community-scoped must not be served to parties outside the named community once the substrate supports scope enforcement.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum Visibility {
    PublicDetailed,
    PublicMinimal,
    PublicAggregateOnly,
    CommunityScoped,
    Private,
}

/// Reference to a community-published action vocabulary. Determines how 'action' identifiers are resolved and subsumed.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct VocabRef {
    /// Content hash pinning a specific vocabulary revision.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cid: Option<String>,
    /// AT-URI pointing to the vocabulary record.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uri: Option<idiolect_records::AtUri>,
}

/// CaveatSeverity.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum CaveatSeverity {
    Info,
    Warn,
    Error,
}

/// LensRefDirection.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum LensRefDirection {
    Unidirectional,
    Bidirectional,
}