@oimlsmart/primmel-packages 0.1.0

package/oiml-smart-core/entities/engagement.prl

@@ -0,0 +1,323 @@
+class Engagement#data {
+  store { engagements }
+  description { "The commercial negotiation between two parties around work (TODO.federation/02 introduced the IA/applicant pair; TODO.adoption/07 generalized it): a requester approaches a provider with an inquiry, receives a financial quotation, signs an agreement, and only then does the technical record exist. The kind fixes the pair: ia_applicant (a manufacturer approaches an Issuing Authority; provenance ISO/IEC 17065:2012, 7.2 (the application information the body obtains) for the inquiry, 7.3.1 (application review) for the quotation review, 4.1.2 (the legally enforceable agreement) for the agreement leg, 7.3.4 (declining without competence) for the provider_declines leg; the fee content of the quotation per PD-05 §4.2.8/§4.2.9), ia_tl (an Issuing Authority negotiates test work with a Test Laboratory), tl_applicant (a manufacturer negotiates development testing with a Test Laboratory directly, outside any certification flow). Pure record-keeping: the module records quotations and agreements, it never moves money (TODO.adoption/09 carries the payment evidence). The funnel is the `engagement` state machine (INQUIRY → QUOTED → AGREED → CONVERTED, with DECLINED and WITHDRAWN legs and the PENDING_EXTERNAL park for the acts that genuinely happen off-platform); once CONVERTED (or DECLINED/WITHDRAWN) the record is read-only and, for ia_applicant, the linked Application carries the subject data forward. Only ia_applicant negotiations convert: the conversion_offered guard on the machine holds the kind." }
+  indexes { manufacturer_id issuing_authority_id test_laboratory_id status standard_id kind }
+  id: string {
+    modality SHALL
+  }
+  standard_id: string {
+    modality SHALL
+  }
+  engagement_number: string {
+    modality SHALL
+    definition "The provider's reference (ENG-<provider>-<year>-<seq>), minted like the application number"
+  }
+  kind: enum {
+    modality SHALL
+    definition "The negotiation pair (TODO.adoption/07): ia_applicant (requester = the applicant manufacturer, provider = the Issuing Authority), ia_tl (requester = the Issuing Authority, provider = the Test Laboratory), tl_applicant (requester = the applicant manufacturer, provider = the Test Laboratory). Fixed at recording; the kind drives the party refs, the console views, and the defaults."
+    enum_values { ia_applicant ia_tl tl_applicant }
+  }
+  manufacturer_id: reference(Manufacturer) [0..1] {
+    modality MAY
+    definition "The applicant organization (ISO/IEC 17065:2012, 7.2: the client's identity). The requester on ia_applicant and tl_applicant negotiations; absent on ia_tl. The applicant-side org visibility keys on it, as with Application.manufacturer_id"
+    on_delete restrict
+    required false
+  }
+  issuing_authority_id: reference(IssuingAuthority) [0..1] {
+    modality MAY
+    definition "The Issuing Authority party: the provider on ia_applicant (the inquiry is addressed to it), the requester on ia_tl; absent on tl_applicant. The IA-side org visibility keys on it, as with Application.issuing_authority_id"
+    on_delete restrict
+    required false
+  }
+  test_laboratory_id: reference(TestLaboratory) [0..1] {
+    modality MAY
+    definition "The Test Laboratory party: the provider on ia_tl and tl_applicant negotiations; absent on ia_applicant. The laboratory-side org visibility keys on it, as with TestRequest.assigned_laboratory_id"
+    on_delete restrict
+    required false
+  }
+  subject_designation: string {
+    modality SHALL
+    definition "The subject's designation as the requester states it: the instrument's spec-sheet summary on ia_applicant, the scope of work on ia_tl and tl_applicant. The technical record proper starts at the Application"
+  }
+  subject_description: text [0..1] {
+    modality MAY
+    definition "What the subject is and the work asked for, as enquired (intended use, measuring range, the spec sheet's prose, the scope of the test work)"
+  }
+  inquirer_name: string [0..1] {
+    modality MAY
+    definition "The person who made the inquiry (the requester's contact)"
+  }
+  inquirer_email: string [0..1] {
+    modality MAY
+  }
+  inquirer_phone: string [0..1] {
+    modality MAY
+  }
+  owner: string [0..1] {
+    modality MAY
+    definition "The provider-side officer owning the negotiation (audit provenance)"
+  }
+  status: enum {
+    modality SHALL
+    definition "The negotiation funnel (the `engagement` state machine): INQUIRY → QUOTED → AGREED → CONVERTED, DECLINED from INQUIRY (provider_declines, ISO/IEC 17065:2012, 7.3.4) or QUOTED (requester_declines), WITHDRAWN from the open states (requester_withdraws), and the PENDING_EXTERNAL park (TODO.adoption/07: the negotiation continues off-platform; either party records the claimed outcome with its document and provenance). CONVERTED/DECLINED/WITHDRAWN are terminal: the record is then read-only."
+    enum_values { INQUIRY QUOTED AGREED CONVERTED DECLINED WITHDRAWN PENDING_EXTERNAL }
+  }
+  quotation_id: reference(Quotation) [0..1] {
+    modality MAY
+    definition "The current quotation; a re-issue supersedes the previous one (its status goes SUPERSEDED), never edits it in place"
+    on_delete nullify
+    required false
+  }
+  agreement_id: reference(ConsultingAgreement) [0..1] {
+    modality MAY
+    definition "The agreement record (ISO/IEC 17065:2012, 4.1.2 on ia_applicant; the same record-keeping doctrine on the other kinds)"
+    on_delete nullify
+    required false
+  }
+  converted_application_id: reference(Application) [0..1] {
+    modality MAY
+    definition "The Application an ia_applicant negotiation converted into (the only kind that converts): set by the conversion, then the negotiation is read-only"
+    on_delete nullify
+    required false
+  }
+  decline_reason: text [0..1] {
+    modality MAY
+    definition "Recorded on the DECLINED leg (provider_declines / requester_declines / external_decline_recorded): the reason is never silently dropped"
+  }
+  withdrawal_reason: text [0..1] {
+    modality MAY
+    definition "Recorded on the requester_withdraws leg"
+  }
+  external_note: text [0..1] {
+    modality MAY
+    definition "What the parties are settling off-platform while the negotiation parks (the PENDING_EXTERNAL leg's recorded reason: a phone negotiation, a legal review, shipping terms)"
+  }
+  external_recorded_by: string [0..1] {
+    modality MAY
+    definition "Who recorded the off-platform outcome (the claimant's name). The platform records the claimed outcome with the claimant's provenance; it never pretends to have witnessed the act itself"
+  }
+  external_outcome_date: date [0..1] {
+    modality MAY
+    definition "The date the parties state they settled off-platform, in the claimant's wording (e.g. agreed on 2026-08-20)"
+  }
+  quoted_date: datetime [0..1] {
+    modality MAY
+  }
+  agreed_date: datetime [0..1] {
+    modality MAY
+    definition "Both signatures on the agreement (ISO/IEC 17065:2012, 4.1.2), or the recording of a claimed off-platform agreement"
+  }
+  converted_date: datetime [0..1] {
+    modality MAY
+  }
+  declined_date: datetime [0..1] {
+    modality MAY
+  }
+  withdrawn_date: datetime [0..1] {
+    modality MAY
+  }
+  created: datetime {
+    modality SHALL
+  }
+  modified: datetime {
+    modality SHALL
+  }
+}
+
+class Quotation#data {
+  store { quotations }
+  description { "The provider's financial quotation (TODO.federation/02 for the engagement parent; TODO.adoption/07 for the test-request quote leg; the fee content per PD-05 §4.2.8/§4.2.9): priced line items with computed amounts and a computed total, a currency, a validity date, and the stated timeline and conditions. Exactly one parent: an Engagement (the negotiation primitive) or a TestRequest (the dispatched request the laboratory quotes against). Record-keeping only: issuance walks the parent INQUIRY → QUOTED (the engagement) or ISSUED → QUOTED (the test request); acceptance rides the agreement signature (the engagement) or the requester's accept act (the test request). A re-quotation supersedes, never edits an issued quotation." }
+  indexes { engagement_id test_request_id test_laboratory_id status }
+  id: string {
+    modality SHALL
+  }
+  standard_id: string {
+    modality SHALL
+  }
+  engagement_id: reference(Engagement) [0..1] {
+    modality MAY
+    definition "The engagement this quotation prices (set when the parent is a negotiation)"
+    on_delete cascade
+    required false
+  }
+  test_request_id: reference(TestRequest) [0..1] {
+    modality MAY
+    definition "The dispatched test request this quotation prices (set when the parent is the TODO.adoption/07 quote leg). Exactly one of engagement_id / test_request_id is set."
+    on_delete cascade
+    required false
+  }
+  quotation_number: string {
+    modality SHALL
+    definition "The provider's reference (QUO-<provider>-<year>-<seq>)"
+  }
+  line_items: reference(QuotationLineItem) [1..*] {
+    modality SHALL
+    definition "The priced lines (application fee, evaluation days, per-test charges, …); every amount is computed by the quotation service, never keyed by hand"
+  }
+  currency: string {
+    modality SHALL
+    definition "The ISO 4217 currency code every line amount and the total are expressed in"
+  }
+  total_amount: number {
+    modality SHALL
+    definition "The sum of the line items' computed amounts: computed by the quotation service, stored for the record (the requester sees the same number the provider composed)"
+  }
+  valid_until: date [0..1] {
+    modality MAY
+    definition "The quotation's validity date; past it the quotation has lapsed (displayed, never silently enforced)"
+  }
+  timeline: string [0..1] {
+    modality MAY
+    definition "The provider's stated delivery timeline (the quote leg's content, TODO.adoption/07: price, currency, timeline, conditions, validity)"
+  }
+  conditions: text [0..1] {
+    modality MAY
+    definition "The commercial conditions the provider attaches to the quotation (payment terms, validity conditions, scope caveats), in the provider's wording"
+  }
+  status: enum {
+    modality SHALL
+    definition "DRAFT (being composed) → ISSUED (sent to the requester with the parent's hop into QUOTED) → ACCEPTED (the requester's acceptance act) | DECLINED (the requester declines) — or SUPERSEDED when a re-quotation replaces it. Field writes with audit, not a machine: the parent's funnel is the lifecycle that matters."
+    enum_values { DRAFT ISSUED ACCEPTED DECLINED SUPERSEDED }
+  }
+  notes: text [0..1] {
+    modality MAY
+  }
+  manufacturer_id: reference(Manufacturer) [0..1] {
+    modality MAY
+    definition "Denormalized from the parent (the applicant party, when the pair carries one): the org-visibility index fields are the entities' REAL fields (the requester reads their quotation directly)"
+    on_delete restrict
+    required false
+  }
+  issuing_authority_id: reference(IssuingAuthority) [0..1] {
+    modality MAY
+    definition "Denormalized from the parent (the Issuing Authority party, when the pair carries one)"
+    on_delete restrict
+    required false
+  }
+  test_laboratory_id: reference(TestLaboratory) [0..1] {
+    modality MAY
+    definition "Denormalized from the parent (the Test Laboratory party, when the pair carries one: the provider on ia_tl and tl_applicant, the quoting laboratory on the test-request leg)"
+    on_delete restrict
+    required false
+  }
+  issued_date: datetime [0..1] {
+    modality MAY
+  }
+  accepted_date: datetime [0..1] {
+    modality MAY
+  }
+  declined_date: datetime [0..1] {
+    modality MAY
+  }
+  decline_reason: text [0..1] {
+    modality MAY
+    definition "Recorded when the requester declines the quotation"
+  }
+  created: datetime {
+    modality SHALL
+  }
+  modified: datetime {
+    modality SHALL
+  }
+}
+
+class QuotationLineItem#data {
+  description { "One priced line of a Quotation (TODO.federation/02): what is charged, how many units, the unit price, and the computed amount. Embedded on Quotation.line_items; the amount is quantity × unit_price computed by the quotation service (round-half-up to two decimals), never keyed by hand." }
+  helper { true }
+  item: text {
+    modality SHALL
+    definition "What the line charges for (application fee, evaluation day, test charge, …)"
+  }
+  quantity: number {
+    modality SHALL
+  }
+  unit_price: number {
+    modality SHALL
+    definition "The per-unit price in the quotation's currency"
+  }
+  amount: number {
+    modality SHALL
+    definition "quantity × unit_price, computed by the quotation service and stored for the record"
+  }
+}
+
+class ConsultingAgreement#data {
+  store { consultingAgreements }
+  description { "The agreement record against a negotiation (TODO.federation/02; ISO/IEC 17065:2012, 4.1.2 on ia_applicant: certification activities are under a legally enforceable agreement): the agreement date, the signed document references, and the two signature legs (requester and provider). Both signatures complete the negotiation's QUOTED → AGREED hop; either party may sign first (the requester's portal acceptance is one leg; the provider's desk records the other, white-gloves deployments record both at the provider desk). When the act genuinely happened off-platform (TODO.adoption/07's pending-external pattern), the record instead carries the claimed outcome: the external_recorded_* provenance names the claimant and the signature legs stay empty, because the platform never witnessed them. The agreement DOCUMENTS ride as references: the platform records what was supplied, the signed bytes stay with the parties' records (or in the TODO.adoption/03 blob store when bound)." }
+  indexes { engagement_id test_laboratory_id status }
+  id: string {
+    modality SHALL
+  }
+  standard_id: string {
+    modality SHALL
+  }
+  engagement_id: reference(Engagement) {
+    modality SHALL
+    definition "The negotiation this agreement governs"
+    on_delete cascade
+    required true
+  }
+  agreement_date: date [0..1] {
+    modality MAY
+    definition "The date on the agreement document"
+  }
+  documents: reference(DocumentRef) [0..*] {
+    modality MAY
+    definition "The signed agreement document(s) as references (document_type + reference): the record carries what was supplied, never a copy"
+  }
+  status: enum {
+    modality SHALL
+    definition "DRAFT (recorded, signatures outstanding) → SIGNED (both parties signed and the negotiation walks QUOTED → AGREED on the completing signature, or the off-platform outcome was recorded with its claimant provenance from PENDING_EXTERNAL)"
+    enum_values { DRAFT SIGNED }
+  }
+  signed_by_requester: string [0..1] {
+    modality MAY
+    definition "Who signed for the requester organization"
+  }
+  requester_signed_date: datetime [0..1] {
+    modality MAY
+  }
+  signed_by_provider: string [0..1] {
+    modality MAY
+    definition "Who signed for the provider organization"
+  }
+  provider_signed_date: datetime [0..1] {
+    modality MAY
+  }
+  external_recorded_by: string [0..1] {
+    modality MAY
+    definition "Set when the agreement is the recorded outcome of an off-platform act (TODO.adoption/07): the claimant's name. The signature legs stay empty on such a record; the platform records the claimed outcome, never a witnessed signature."
+  }
+  external_recorded_date: datetime [0..1] {
+    modality MAY
+    definition "When the off-platform outcome was recorded"
+  }
+  notes: text [0..1] {
+    modality MAY
+  }
+  manufacturer_id: reference(Manufacturer) [0..1] {
+    modality MAY
+    definition "Denormalized from the parent negotiation (the applicant party, when the pair carries one): the org-visibility index fields are the entities' REAL fields"
+    on_delete restrict
+    required false
+  }
+  issuing_authority_id: reference(IssuingAuthority) [0..1] {
+    modality MAY
+    definition "Denormalized from the parent negotiation (the Issuing Authority party, when the pair carries one)"
+    on_delete restrict
+    required false
+  }
+  test_laboratory_id: reference(TestLaboratory) [0..1] {
+    modality MAY
+    definition "Denormalized from the parent negotiation (the Test Laboratory party, when the pair carries one)"
+    on_delete restrict
+    required false
+  }
+  created: datetime {
+    modality SHALL
+  }
+  modified: datetime {
+    modality SHALL
+  }
+}
+

package/oiml-smart-core/entities/instrument.prl

@@ -0,0 +1,359 @@
+class QuantityValue#data {
+  description { "Number + optional unit — the INV-1 workhorse (\"no bare numbers\"). Instantiation of metamodel Module A QuantityValue, reduced to the two fields the R 60 parameter layer needs." }
+  helper { true }
+  value: any {
+    modality SHALL
+    definition "Decimal or string value (string for enum-like parameter values)"
+  }
+  unit: string [0..1] {
+    modality MAY
+    definition "Unit id from value-types.yaml units (kg, g, t, degC, V, mV/V, %, v, counts/v, ...); absent only for dimensionless/string values"
+  }
+}
+
+class CustodyEvent#data {
+  description { "Append-only chain-of-custody record, embedded in MeasuringInstrumentSample.custody_events" }
+  helper { true }
+  sample_id: reference(MeasuringInstrumentSample) {
+    modality SHALL
+    on_delete cascade
+    required true
+  }
+  event_type: enum {
+    modality SHALL
+    enum_values { REQUESTED SHIPPED RECEIVED ASSIGNED_TO_TEST RETURNED DISPOSED }
+  }
+  from_party_id: string [0..1] {
+    modality MAY
+    definition "Party that held the sample before this event"
+  }
+  to_party_id: string {
+    modality SHALL
+    definition "Party that holds the sample after this event"
+  }
+  timestamp: datetime {
+    modality SHALL
+  }
+  notes: text [0..1] {
+    modality MAY
+  }
+}
+
+class OperationalStateEntry#data {
+  description { "One entry of a sample's operational-state trajectory (TODO.roadmap/07 + task 29, primmel StateTrajectoryEntry): the machine ENTERED `state` at `at` because `fired_by` recorded the transition fire. Append-only evidence — lands in the run's trace next to the conditions log." }
+  helper { true }
+  state: string {
+    modality SHALL
+    definition "Node of the operational machine entered (e.g. warming_up, ready)"
+  }
+  at: datetime {
+    modality SHALL
+    definition "ISO-8601 timestamp of the entry"
+  }
+  fired_by: string {
+    modality SHALL
+    definition "Who/what fired the transition (operator name, process step id; '' = genesis)"
+  }
+}
+
+class OperationalState#data {
+  description { "A sample's current node in one OPERATIONAL state machine (TODO.roadmap/07 + task 29) — instance-level data of the machine declared in data/<rec>/model/state.yaml. Strictly separate from `status` (the measuring_instrument_sample LIFECYCLE machine): the families never mix (primmel C38)." }
+  helper { true }
+  machine: string {
+    modality SHALL
+    definition "Id of the operational state machine (model/state.yaml state_machines[].id)"
+  }
+  current: string {
+    modality SHALL
+    definition "The machine's current node (e.g. off, warming_up, ready, measuring)"
+  }
+  trajectory: reference(OperationalStateEntry) [0..*] {
+    modality MAY
+    definition "Append-only state-entry log (embedded)"
+    on_delete cascade
+  }
+}
+
+class PhysicalDimensions#data {
+  description { "The sample's physical dimensions as registered on receipt (R 60-3, 4.9.10 — the report form's load-cell-dimensions entry, whose table carries the pictures/drawings of the dimensions). Every facet is an optional quantity-with-unit in mm; only the dimensions relevant to the instrument's shape are recorded (a cylindrical load cell records height + diameter, never length/width)." }
+  helper { true }
+  length: reference(QuantityValue) [0..1] {
+    modality MAY
+    definition "Overall length (QuantityValue { value, unit: mm })"
+  }
+  width: reference(QuantityValue) [0..1] {
+    modality MAY
+    definition "Overall width (QuantityValue { value, unit: mm })"
+  }
+  height: reference(QuantityValue) [0..1] {
+    modality MAY
+    definition "Overall height (QuantityValue { value, unit: mm })"
+  }
+  diameter: reference(QuantityValue) [0..1] {
+    modality MAY
+    definition "Body diameter (QuantityValue { value, unit: mm })"
+  }
+}
+
+class MeasuringInstrumentModelFamily#data {
+  store { measuringInstrumentModelFamilies }
+  description { "Family of measuring instruments (OIML V 1:2022, 4.02; R 60-1, 3.4.2). HAS MANY Models (optionally via Groups). Its classification and parameters act as defaults inherited by its groups/models (INV-10)." }
+  indexes { manufacturer_id standard_id }
+  id: string {
+    modality SHALL
+  }
+  standard_id: string {
+    modality SHALL
+  }
+  family_designation: string {
+    modality SHALL
+    definition "Human-readable family designation (e.g. 'ACME LC-500 Series')"
+  }
+  family_code: string [0..1] {
+    modality MAY
+    definition "Short code used in certificate numbers and URIs"
+  }
+  manufacturer_id: reference(Manufacturer) {
+    modality SHALL
+    on_delete restrict
+    required true
+  }
+  classification: map<dimension_id, string> [0..1] {
+    modality MAY
+    definition "Family-level dimension defaults (family-scope axes: technology, humidity_class, construction)"
+  }
+  parameters: map<attribute_id, QuantityValue> [0..1] {
+    modality MAY
+    definition "Family-scope attribute defaults (attributes.yaml scope: family — e_min, e_lim, p_lc, t_min, t_max, rated_output, input_impedance, output_impedance, recommended_excitation, excitation_maximum, safe_overload, transducer_material, atmospheric_protection)"
+  }
+  created: datetime {
+    modality SHALL
+  }
+  modified: datetime {
+    modality SHALL
+  }
+}
+
+class MeasuringInstrumentModelGroup#data {
+  store { measuringInstrumentModelGroups }
+  description { "Sub-grouping within a MeasuringInstrumentModelFamily. A group carries the metrological characteristics its member Models share (accuracy class, n_lc, y, z, dr, ...); Models resolve them by delegation (INV-10). Within a group, Models differ only by e_max (R 60-2, Annex D)." }
+  indexes { family_id manufacturer_id standard_id }
+  id: string {
+    modality SHALL
+  }
+  standard_id: string {
+    modality SHALL
+  }
+  family_id: reference(MeasuringInstrumentModelFamily) {
+    modality SHALL
+    on_delete cascade
+    required true
+  }
+  manufacturer_id: reference(Manufacturer) {
+    modality SHALL
+    definition "Denormalized from family_id.manufacturer_id"
+    on_delete restrict
+    required true
+  }
+  group_label: string {
+    modality SHALL
+    definition "Compact label combining class + n_lc (e.g. 'C6', 'B10', 'C3')"
+  }
+  classification: map<dimension_id, string> [0..1] {
+    modality MAY
+    definition "Group-scope dimensions (accuracy_class, load_type; humidity_class override of the family default)"
+  }
+  parameters: map<attribute_id, QuantityValue> [0..1] {
+    modality MAY
+    definition "Group-identical characteristics (attributes.yaml scope: group — n_lc, v_min, y, z, dr, mpe, mpe_lc, construction_type)"
+  }
+  created: datetime {
+    modality SHALL
+  }
+  modified: datetime {
+    modality SHALL
+  }
+}
+
+class MeasuringInstrumentModel#data {
+  store { measuringInstrumentModels }
+  description { "A model of measuring instrument — the subject of type evaluation and approval. Attribute values not set here resolve through group -> family delegation (INV-10)." }
+  indexes { family_id group_id manufacturer_id standard_id }
+  id: string {
+    modality SHALL
+  }
+  standard_id: string {
+    modality SHALL
+  }
+  model_designation: string {
+    modality SHALL
+    definition "Specific model designation (e.g. 'ACME-LC-500-C-5kg')"
+  }
+  manufacturer_id: reference(Manufacturer) {
+    modality SHALL
+    on_delete restrict
+    required true
+  }
+  family_id: reference(MeasuringInstrumentModelFamily) {
+    modality SHALL
+    on_delete restrict
+    required true
+  }
+  group_id: reference(MeasuringInstrumentModelGroup) [0..1] {
+    modality MAY
+    on_delete restrict
+    required false
+  }
+  hardware_revision: string [0..1] {
+    modality MAY
+  }
+  type_approval_ref: reference(Certificate) [0..1] {
+    modality MAY
+    definition "Certificate issued for this model — filled after D3 approval"
+    on_delete nullify
+    required false
+  }
+  description: text [0..1] {
+    modality MAY
+  }
+  classification: map<dimension_id, string> [0..1] {
+    modality MAY
+    definition "Model dimension values/overrides (technology, accuracy_class, humidity_class, load_type)"
+  }
+  parameters: map<attribute_id, QuantityValue> [0..1] {
+    modality MAY
+    definition "Model-scope attributes (e_max, mr_max, warm_up_time, power_voltage, interfaces, output_signal, software_identification; overrides of inherited group/family values)"
+  }
+  capabilities: string[] [0..*] {
+    modality MAY
+    definition "Capability ids from data/r60/model/capabilities.yaml"
+  }
+  created: datetime {
+    modality SHALL
+  }
+  modified: datetime {
+    modality SHALL
+  }
+}
+
+class MeasuringInstrumentSample#data {
+  store { measuringInstrumentSamples }
+  description { "A physical instance of a MeasuringInstrumentModel submitted for type evaluation. Tracks receipt, dispatch to test labs, and return/disposal through the embedded custody_events log (PD-05 §4.3)." }
+  indexes { model_id application_id manufacturer_id serial_number status standard_id }
+  id: string {
+    modality SHALL
+  }
+  standard_id: string {
+    modality SHALL
+  }
+  sample_number: string [0..1] {
+    modality MAY
+    definition "IA-assigned sample number (e.g. 'S-2024-001')"
+  }
+  serial_number: string {
+    modality SHALL
+    definition "Manufacturer's serial number on the physical instrument"
+  }
+  model_id: reference(MeasuringInstrumentModel) {
+    modality SHALL
+    definition "Catalog model this sample is an instance of"
+    on_delete restrict
+    required true
+  }
+  manufacturer_id: reference(Manufacturer) {
+    modality SHALL
+    on_delete restrict
+    required true
+  }
+  application_id: reference(Application) [0..1] {
+    modality MAY
+    definition "Application this sample was logged against"
+    on_delete restrict
+    required false
+  }
+  manufacturing_date: date [0..1] {
+    modality MAY
+  }
+  received_date: date [0..1] {
+    modality MAY
+  }
+  condition: enum {
+    modality SHALL
+    definition "The condition the sample arrived in, recorded at receipt registration (the physical instrument's received state)"
+    enum_values { NEW USED REFURBISHED DAMAGED }
+  }
+  condition_notes: text [0..1] {
+    modality MAY
+  }
+  photographs: reference(DocumentRef) [0..*] {
+    modality MAY
+    definition "Receipt photograph(s) of the physical instrument (R 60-3, 4.9.4 — the report form carries the sample's photographs); the document-store blob slots carry the bytes when the store is bound, the file-name reference otherwise"
+  }
+  status: enum {
+    modality SHALL
+    definition "Lifecycle per evaluation/state-machines.yaml measuring_instrument_sample machine"
+    enum_values { REQUESTED IN_TRANSIT RECEIVED IN_TESTING TESTING_COMPLETE RETURNED RETAINED DESTROYED DISPOSED }
+  }
+  current_location: string [0..1] {
+    modality MAY
+  }
+  current_custodian_id: string [0..1] {
+    modality MAY
+    definition "Reference to the org currently holding the sample (IA, lab, manufacturer)"
+  }
+  custody_events: reference(CustodyEvent) [0..*] {
+    modality SHALL
+    definition "Append-only chain-of-custody log (embedded)"
+    on_delete cascade
+  }
+  disposal_method: enum [0..1] {
+    modality MAY
+    enum_values { RETURNED RECYCLED DESTROYED RETAINED }
+  }
+  disposal_date: date [0..1] {
+    modality MAY
+  }
+  disposal_certificate: reference(DocumentRef) [0..1] {
+    modality MAY
+  }
+  test_context: map<attribute_id, QuantityValue> [0..1] {
+    modality MAY
+    definition "Sample-scope test-dependent attributes (attributes.yaml origin: test-dependent — d_min, d_max, v, n, mr, conversion_factor_f); values under test, never inherited downward"
+  }
+  physical_dimensions: reference(PhysicalDimensions) [0..1] {
+    modality MAY
+    definition "Physical dimensions registered on receipt (R 60-3, 4.9.10 — the report form's load-cell-dimensions entry); embedded, each facet a QuantityValue in mm"
+  }
+  selected_for_evaluation: boolean [0..1] {
+    modality MAY
+    definition "The IA's selection of this sample for the type evaluation (R 60-3, 4.7 — selection of the sample(s) tested): the evaluation tests a subset of the received samples; absent/false = not selected. Only a registered (received) sample is selectable."
+  }
+  selection_justification: text [0..1] {
+    modality MAY
+    definition "The recorded justification of the selection decision (R 60-3, 4.7.2 — justification of the selection of the test sample(s), referring to R 60-2, 2.3/2.4 and Annex D)"
+  }
+  verification_state: enum [0..1] {
+    modality MAY
+    definition "Verification lifecycle state (TODO.roadmap/21, metamodel v0.6.1) — the sample_verification state machine of evaluation/state-machines.yaml: NOT_VERIFIED → VERIFIED (a verification passes) → REVERIFICATION_DUE (timer: validity window elapsed) | INVALIDATED (signal: an out-of-cycle trigger such as a tyre change) → VERIFIED (re-verification passes). Absent = never verified."
+    enum_values { NOT_VERIFIED VERIFIED REVERIFICATION_DUE INVALIDATED }
+  }
+  seals: reference(SealStatus) [0..*] {
+    modality MAY
+    definition "Current seal status on the sample (embedded) — set/renewed by passed verifications (marking and securing, e.g. R 91-1, 7.13/8.2.4)"
+  }
+  verification_signals: reference(VerificationSignal) [0..*] {
+    modality MAY
+    definition "Posted out-of-cycle verification signals (embedded) — the signal-event channel of the re-verification triggers (e.g. tyre-change on an ego speed meter, R 91-1, 6.15.3 Note 2); consumed by the trigger engine"
+  }
+  operational_state: reference(OperationalState) [0..1] {
+    modality MAY
+    definition "The sample's current node in the rec's OPERATIONAL state machine (data/<rec>/model/state.yaml, TODO.roadmap/07 + task 29 — e.g. the R 144 warm-up machine off → warming_up → ready → measuring). Instance-level HAS state with an append-only trajectory; tests gate on it via the precondition `state:` facet (violation ⇒ run invalid, never fail). Absent = no operational state tracked (the gate reads the machine's initial node). Strictly separate from `status` (lifecycle family)."
+  }
+  created: datetime {
+    modality SHALL
+  }
+  modified: datetime {
+    modality SHALL
+  }
+}
+