DWIS.RigOS.Contracts.DownholeMechanical 1.1.0

DWIS downhole mechanical contract v1

Vendor-neutral snapshots group comparable channels from repeated equipment along a drill string. Equipment IDs, sensor IDs and SI distance from bit are resolved from the current Blackboard DrillString JSON. The wire contract owns projections of identity and measurements; it does not redefine the DrillString domain model. Statistics, raw/corrected qualification, bias/calibration, axis and telemetry are independent explicit fields. JSON names are PascalCase; enums are strings. Schema and metadata live at /DownholeMechanical/v1/{schema,metadata}.json through DWIS Contracts. Null means unavailable, with a reason. Unsupported channels are omitted. No statistics are invented. Package version 1.1.0 is independent of the existing Common family; packing is supported, publication requires a separate authorized release. Contract documents are embedded and included in the package.

Consumers call DownholeMechanicalContract.Validate after deserialization for identity/reference and cross-field rules beyond JSON Schema. Required wire members must be present; enums are strings. Measurement keys include equipment UUID, channel ID and telemetry.

Cartesian and polar bending

The additive 1.1.0 package retains the v1 route and existing Cartesian payloads. Existing enum numeric values and wire fields are unchanged; compiled consumers must upgrade before consuming the newly introduced quantity tokens.

New polar quantities require Axis=None in both C# validation and JSON Schema. Existing unqualified/other-axis BendingMoment channels retain their prior meaning; they must not be guessed to be polar magnitudes. Each new quantity has explicit bendingRepresentation metadata (Magnitude or Angle). Existing Cartesian, polar, or both forms may be supplied in the same snapshot. Partial pairs remain valid because channels and telemetry may update independently. No new required wire fields or mandatory coordinate pairs are introduced.

Angles start from +X and increase towards +Y in the instrument-local plane. The metadata describes magnitude=hypot(x,y), angle=atan2(y,x), x=magnitude*cos(angle) and y=magnitude*sin(angle). Consumers use supplied coordinates first and derive only missing coordinates. Pair only measurements with matching equipment, position, source time, statistic, processing, role and telemetry. Derived vectors use measurement-role None/Average statistics; independent extrema, standard deviations, biases/calibrations and asynchronous samples do not define a convertible vector. Zero Cartesian vectors have no derived direction. Angles need not be normalized; equivalent orientations differ by multiples of 2π. No spatial rotation, axis permutation or new samples are inferred.

The shared bridge accepts polar source channels and converts radians/degrees to SI. Source engineering-unit IDs 1–25 are unchanged; radians/degrees append IDs 26/27. Negative source magnitudes become null with InvalidValue. A signed bending offset belongs to a suitably qualified Cartesian/unspecified moment channel, not a negative physical magnitude.