Wetware World

Format reference

Design rules

A conformance code asks whether the file is well-formed. A design rule asks whether the design will work. Fifteen shipped rules, each with a threshold, a remedy and a source, and a package that passes validation while failing two of them.

Shipped rules
15
Status
advisory
Graded
1
Appendix
C.5

Definition

A WWD design rule answers a different question from a conformance code. A conformance code asks whether the file is well-formed and internally consistent. A design rule asks whether the design will work. Appendix C.5 of the WWD 0.1 draft carries fifteen shipped design rules under the DFM prefix, each with a fixed severity, a stated threshold and a literature source. A design-rule finding is advisory with respect to conformance: a package MAY conform to WWD and still fail every rule in the table, because WWD does not own the physics. An implementation MUST NOT report a DFM code as a conformance error, and MUST NOT suppress one because the package is otherwise valid. A severity written ERROR to WARNING is graded on a cited range, and a graded rule MUST report which end of the range its severity was decided against and MUST report the margin at both ends. Every other DFM severity is fixed, and an implementation MUST NOT vary one.

A design rule is a named, sourced condition over the content of a design document. It reads component kind, dimensions, fields, interfaces, biology, shipping and the acceptance criteria, computes a number, and compares it with a threshold drawn from published work. When the condition holds it emits a finding: a code, a severity, a message carrying the numbers it computed, a remedy, and the citation the threshold rests on.

A finding is not a conformance result. Conformance codes and design rules answer different questions and are reported in different channels. The verdict line carries errors, warnings and disposition. Design-rule findings are printed under a separate heading and change none of them.

The severity vocabulary

Four values, one of them graded.

DFM severities
Severity Meaning Rules
ERRORThe condition holds against the stated threshold, and the threshold is a hard number.DFM-002, DFM-007, DFM-008, DFM-013, DFM-014, DFM-015
WARNINGThe condition holds and the threshold is a guideline, or the finding reports a missing declaration rather than a violated bound.DFM-003, DFM-004, DFM-005, DFM-006, DFM-009, DFM-010, DFM-011, DFM-012, DFM-016, DFM-INTERNAL
INFOA recorded fact about the design that changes how a later rule reads, and is not a defect.DFM-014 with a custody reference present
ERROR to WARNINGGraded on a cited range. The finding MUST name the end of the range its severity was decided against and MUST report the margin at both ends.DFM-001

A DFM severity other than the graded one is fixed, and an implementation MUST NOT vary it. A rule whose severity moves for any reason other than a stated, cited range is an implementation making its own judgement in a table a reader is entitled to read as normative.

The shipped rules

Every rule the reference validator applies, with its threshold and its source.

WWD 0.1 design rules, Appendix C.5, as implemented in validator/wwd/dfm.py
Code Severity What it checks Threshold or condition What to change Source
DFM-001 ERROR to WARNING A tissue construct with no declared oxygen transport is thicker than diffusion can supply. Component kind is contractile_tissue, tissue_construct, neural_culture or organoid, no fluidic interface and no porosity, vascular-density, capillary-density, perfusion-rate or oxygen-carrier field. Smallest transport-limiting dimension d, medium on two faces. Fires when d minus 2 x 100 um is positive. ERROR when d minus 2 x 200 um is also positive, WARNING when only the conservative end is exceeded. Reduce thickness, add a fluidic or perfusion interface, declare a porosity or vascular-density field, or use an oxygen-carrier material. Rouwkema 2009 Biotechnol Genet Eng Rev 26:163; Rafique 2023 PMC10295847
DFM-002 ERROR A force criterion asks for more specific force than the cross-section can deliver. Cross-section from width x thickness, or from cross_sectional_area. Tetanic ceiling 19.3 mN/mm2, twitch ceiling 0.35 of tetanic. ERROR above the ceiling, WARNING above 0.6 of it. Increase the cross-section to the stated area, or lower the requirement to the stated force. Specific force ceiling ~19.3 mN/mm2 after chronic e-stim, WETWARE_SUPPLY_LANDSCAPE.md sec.4.2; Curi Bio Mantarray validation PMC9445471 reports 385-1156 uN twitch
DFM-003 WARNING A contractile component asks for force and declares no adequate alignment target. Kind contractile_tissue with a peak_twitch_force or tetanic_force criterion. WARNING when no wwd:fiber_alignment or wwd:cell_alignment field exists. ERROR when the order parameter S is below 0.30. Add a wwd:fiber_alignment field, director plus order parameter S, with causal_role response and a criterion of its own; or raise S above 0.30, or drop the force requirement. anisotropy report sec.4-6; alignment dominates contractile output
DFM-004 WARNING The alignment director does not lie along the load axis the interfaces imply. An alignment field with a director, and two or more mechanical interfaces, where the x component of the director is below 0.7 in magnitude. Align the director with the anchor-to-anchor axis, or state explicitly why an off-axis architecture is intended. carried by the rule as geometry; the alignment source is DFM-003
DFM-005 WARNING Matrix stiffness sits far outside the window associated with the intended lineage. wwd:ecm_stiffness read in Pa, kPa or MPa. Myogenic window 8-15 kPa for contractile_tissue, neural window 0.1-1 kPa for neural_culture. Fires below half the lower bound or above three times the upper bound. Bring stiffness toward the window, or document why this construct departs from the tissue-mimetic window. durotaxis and matrix-elasticity lineage specification; ARCHITECTURE-NOTES.md field table
DFM-006 WARNING Electrode pitch is too coarse for the spatial claim the package makes. Kind neural_culture with an electrical interface declaring a pitch above 200 um. Use a denser array for single-unit criteria, or restrict acceptance criteria to population measures such as mean firing rate and burst rate. Optimal electrode size and HD-MEA review PMC6498989
DFM-007 ERROR An active-electrode-fraction criterion cannot be satisfied by the declared array. A criterion on active_electrode_fraction with limit L against an array of n electrodes. ERROR when ceil(L x n) exceeds n. WARNING when n is below 16, because each electrode moves the statistic by 1/n. Lower the fraction or increase the electrode count; or use at least 16 electrodes, or declare a wider acceptance band. arithmetic over the declared array; no external source
DFM-008 ERROR A primary population is past its replicative limit. A biology entry with derivation primary. ERROR at passage 20 or above, WARNING at passage 10 or above. Use an earlier passage, or switch to an immortalized or iPSC-derived source with a renewable bank; or qualify the lot at this passage before committing a run. carried by the rule as replicative limit of primary cells
DFM-009 WARNING A critical response criterion carries no yield statement. One or more acceptance criteria with tests_axis response and criticality critical, and no yield block in the results. Add a yield block naming the criterion, the units tested and the units meeting it. CAUSAL-MANUFACTURING-THESIS.md sec.3, yield is a primary engineering parameter for emergent outcomes
DFM-010 WARNING A living component declares no validity window. Any component whose kind is not cell_preparation and which carries no validity_window. Declare validity_window with a time origin such as hours post-seeding or days in vitro, and a from and to interval. carried by the rule; an article at day 7 and at day 21 are different articles under one identifier
DFM-011 WARNING Response targets are declared with no control that could steer them. One or more fields with causal_role response, and no field with causal_role control anywhere in the component. Declare the conditions the producer sets, matrix stiffness, seeding density, anchor spacing, stimulation schedule, as causal_role control fields with imposed_by. CAUSAL-MANUFACTURING-THESIS.md, you set the conditions, the tissue produces the outcome
DFM-012 WARNING Commercial derivative rights are undeclared, unknown, prohibited, service-only, or pending a licence. A biology entry with no licensing block, or commercial_derivative_rights of unknown, prohibited, service_only or requires_license. Prohibited is reported as ERROR; the rest as WARNING. Add biology[].licensing with commercial_derivative_rights; obtain written supplier confirmation before quoting or shipping; source an equivalent line under a resale licence, or attach the executed agreement to licensing.agreement_ref. NEURONTILE-PRODUCT-SPEC.md sec.5 Q1; LICENSING-FINDINGS.md route C
DFM-013 ERROR A research-use-only population is presented as a saleable component. A licensing block with use_restriction research_use_only. Source a commercial-grade equivalent, or sell only as a research-use item with the restriction passed through to the customer. LICENSING-FINDINGS.md, research-use-only terms restrict resale of derivatives
DFM-014 ERROR Customer custody is claimed with no agreement named. A biology entry with custody customer_supplied and no custody_ref. ERROR when absent; INFO when a custody_ref is present, recording that producer resale rights do not apply. Add custody_ref naming the customer licence, MTA or consignment agreement, and ensure it covers the processing steps performed. LICENSING-FINDINGS.md route C
DFM-015 ERROR A live shipment declares no transit limit, or a monophasic waveform runs unbalanced. Shipping state beginning with live and no transit_max_hours, or a monophasic interface with neither charge_balancing nor duty_limit. WARNING when transit_max_hours exceeds the width of a validity window with origin hours_post_seeding. Add transit_max_hours and check it against the validity window; use a biphasic waveform, or declare charge_balancing or duty_limit. WWD 0.1 13.2 shipping state; WWD 0.1 13.2 stimulation waveform
Findings about the check rather than the design
Code Severity What it reports Trigger What to change Source
DFM-016 WARNING A dimension could not be read as a length, so the diffusion check moved axis or did not run. A thickness, width, diameter or height present in dimensions whose value is not a number plus a recognised length unit: um, micron, mm, cm or m. A bare number is not a length. State every dimension as a number and a length unit, for example "0.3 mm". The finding names the axis DFM-001 used instead, or reports that it could not run at all. WWD 0.1 §8.2
DFM-INTERNAL WARNING A rule raised and did not complete. Any exception inside a rule function. The remaining rules still run. Treat the design as unevaluated against that rule rather than as passing it. reported at WARNING so that a check which did not run is not read as a check that passed
Registry references for the property terms the rules read
Rule Property term Canonical unit Registry reference
DFM-005wwd:ecm_stiffnesskPaEngler et al., Cell 126:677 (2006), matrix elasticity directs lineage specification
DFM-003, DFM-004wwd:fiber_alignment1WWD-0.1-DRAFT.md 12.3
DFM-003wwd:cell_alignment1see wwd:fiber_alignment; order parameter S on [0,1], Gasser-Ogden-Holzapfel dispersion
DFM-002wwd:peak_twitch_forceuNCuri Bio Mantarray validation, PMC9445471 (385-1156 uN twitch in engineered human muscle)

A package that passes and fails at once

muscle-strip-highstiff.wwd, run with the design rules on.

The package validates clean. The same command reports two design-rule findings. Both channels come from one run, and neither changes the other.

the verdictpython -m wwd --dfm
muscle-strip-highstiff.wwd
  PASS  (as-built)  errors=0 warnings=0  disposition=pass

Zero errors, zero warnings, disposition pass. The package reaches its conformance class.

the findingssame run, wrapped for width
  manufacturability
    WARNING DFM-001: thickness is 300 um with medium on two faces; under the
      conservative 100 um diffusion depth about 100 um of core is starved; this
      design only works if diffusion reaches the optimistic 200 um
        remedy: reduce thickness, add a fluidic/perfusion interface, declare a
          porosity or vascular-density field, or use an oxygen-carrier material
        source: Rouwkema 2009 Biotechnol Genet Eng Rev 26:163;
          Rafique 2023 PMC10295847
    WARNING DFM-012: skeletal muscle myoblast: no licensing block; commercial
      derivative rights are undeclared
        remedy: add biology[].licensing with commercial_derivative_rights;
          'unknown' is an honest answer, silence is not
        source: NEURONTILE-PRODUCT-SPEC.md sec.5 Q1

Two warnings, each carrying the computed numbers, a remedy and a citation.

What each rule read out of the package
Input Value in the package Effect on the finding
Component kindcontractile_tissueDFM-001 applies to contractile_tissue.
Thickness0.3 mmThe smallest transport-limiting dimension, 300 um.
Transport declarednoneNo fluidic interface and no porosity, vascular-density, perfusion or oxygen-carrier field, so bulk diffusion is the only route.
Conservative margin300 um minus 2 x 100 um = 100 um starvedPositive, so the rule fires.
Optimistic margin300 um minus 2 x 200 um = -100 umNot positive, so the severity is WARNING rather than ERROR.
Cell typeskeletal muscle myoblastDFM-012 reads biology[].licensing on this entry.
Licensing blockabsentRights are undeclared, which is the WARNING branch of DFM-012.
Validity windowhours post-seeding 168 to 336Present, so DFM-010 does not fire.

DFM-001 names the end of the range it decided against and reports the margin at both ends: about 100 um of core starved at the conservative 100 um depth, covered at the optimistic 200 um depth. The optimistic end is not exceeded, so the severity is WARNING.

A rule against a field

What happens when the property has no single number.

Every Core quantitative property slot accepts a quantity string or a field object. A design rule extracts a number and a unit from whatever it finds. A quantity string such as "12 kPa" yields both, and DFM-005 compares it with the 8-15 kPa myogenic window. A field object backed by a mesh attribute carries a store, an array and an interpolation rule, and no single number.

wwd:ecm_stiffnessgraded-strip.wwd
"value": {
  "backing": "mesh_attribute",
  "unit": "kPa",
  "store": "fields/stiffness.vtu",
  "association": "node",
  "array": "stiffness",
  "interpolation": "shape_function",
  "domain": { "kind": "mesh" },
  "out_of_domain": { "policy": "error" }
}

Stiffness varies over the mesh. The extraction returns no scalar, so DFM-005 does not evaluate and emits no finding about this component.

The same discipline governs lengths. A dimension is converted to micrometres only from a number plus a recognised length unit. An unrecognised unit or a bare number returns nothing, and nothing means do not evaluate this rule rather than treat it as a small number.

When that happens the reader is told. DFM-016 names the dimensions that could not be read and states which axis the diffusion check used instead, or that it could not run. A non-positive dimension is skipped in the same way, so no later rule computes a cross-section from impossible geometry.

Rules that read a field-valued property therefore report on the constant spelling only. A graded design states its gradient in the field object and its acceptance target in a criterion, and the criterion is what the conformance codes check.

How an implementation declares its rule set

Opt-in, coverage, and what the output must keep separate.

Obligations on a consumer that runs design rules
ObligationHow the reference implementations meet it
Opt in explicitlyThe reference validator runs no design rule unless asked. python -m wwd package.wwd --dfm runs them; the conformance run does not.
Report the set that ranA rule that raises is reported as DFM-INTERNAL at WARNING, naming the rule function, so the output distinguishes checked and clean from not checked.
Keep findings off the verdictFindings are printed under a manufacturability heading, after the verdict line, and touch neither the error count nor the disposition.
State coverageThe Python implementation carries DFM-001 to DFM-015 plus DFM-016 and DFM-INTERNAL. The TypeScript implementation carries DFM-001 to DFM-015 and holds their severities in a shared code table whose section list is empty for every DFM entry.
Do not re-gradeA DFM severity other than the graded DFM-001 is fixed. An implementation moving one is making its own judgement in a table a reader is entitled to read as normative.

A rule that raised did not pass, it did not run. The reference implementation reports that as DFM-INTERNAL at WARNING rather than as a note, so a check that never executed is not read as a clean one.

What design rules do not cover

The questions answered somewhere else.

Out of scope for Appendix C.5
Question Answered by Rule
Whether the file is well-formedConformance codes, Appendix C.1 to C.4A DFM code MUST NOT be reported as a conformance error, and a package failing every rule can still reach a conformance class.
Whether a value is impossibleRegistry domainsA domain states what is impossible: a fraction above one, a negative count. Whether a value is plausible for a given biology is a design-rule question and is advisory.
A laboratory constraint specific to one processProducer-authored rules, §7.14, codes J01 to J06A design MAY declare named deterministic assertions over values in the package, each with its own identifier, inputs, expression and producer-chosen severity of error or warning.
Whether a requirement is achievableUnit and dimension checks do not attempt itUnit checks catch category errors and transcription mistakes. Achievability in biology is what the design rules answer, and they answer it advisorily.
The physics itselfThe cited literatureThe shipped rules are general, advisory and few. Each threshold is a published number or range carried with its reference.

The shipped set is general and few. A laboratory constraint belongs in the package as a producer-authored rule under §7.14, with its own identifier, inputs, boolean assertion and producer-chosen severity, reported under J01 to J06.

Questions

What is a design-rule finding in WWD?

A statement that a design, as written, meets a published physical, biological or licensing condition under which it is unlikely to work or unlikely to ship. Appendix C.5 carries fifteen such rules under the DFM prefix. Each finding carries a code, a fixed severity, a message naming the numbers it computed, a remedy, and the literature source the threshold rests on.

Can a package be valid and still fail a design rule?

Yes. A design-rule finding is advisory with respect to conformance. A package MAY conform to WWD and still fail every rule in the table, because WWD does not own the physics. An implementation MUST NOT report a DFM code as a conformance error, and MUST NOT suppress one because the package is otherwise valid. muscle-strip-highstiff.wwd is the case: it validates with zero errors and zero warnings and disposition pass, and the same run reports DFM-001 and DFM-012.

What does a graded severity mean?

A severity written ERROR to WARNING means the condition holds against the conservative end of a cited range and may not hold against the optimistic end. DFM-001 is the only graded rule: the oxygen diffusion depth in the literature is 100 to 200 um, a range rather than a number. A graded rule MUST report which end of the range its severity was decided against, and MUST report the margin at both ends. Collapsing the range to one number would assert a precision the literature does not have.

What does the validator report on the high-stiffness muscle strip?

Two warnings. DFM-001, because the 300 um thickness leaves about 100 um of core starved under the conservative 100 um diffusion depth while the optimistic 200 um depth covers it, with the sources Rouwkema 2009 Biotechnol Genet Eng Rev 26:163 and Rafique 2023 PMC10295847. DFM-012, because the skeletal muscle myoblast entry carries no licensing block, so commercial derivative rights are undeclared, sourced to NEURONTILE-PRODUCT-SPEC.md sec.5 Q1.

How does a design rule read a property that is a field rather than a scalar?

It reads the number if there is one and declines to evaluate if there is not. DFM-005 extracts a value and a unit from wwd:ecm_stiffness. A quantity string such as "12 kPa" yields both. A field object backed by a mesh attribute, as in graded-strip.wwd, carries a store, an array and an interpolation rule and no single number, so the extraction returns nothing and the rule does not run. The same holds for lengths: an unrecognised unit or a bare number returns nothing rather than a guess, and DFM-016 reports that the dimension could not be read and names the axis the diffusion check used instead.

Where does a laboratory put its own rules?

In the design, under §7.14. A design MAY declare rules: named deterministic assertions over values in the package. Every rule MUST have an identifier and an assertion, MUST declare a severity of error or warning chosen by the producer, and MUST declare inputs that each resolve to a value in the package. The assertion MUST be an expression under the Core expression profile and MUST evaluate to a boolean. A rule that cannot be evaluated MUST be reported as an error regardless of its declared severity. A consumer MUST evaluate every declared rule and MUST NOT suppress a Core diagnostic because a producer rule passed.

Which rules fire on the shipped example packages?

DFM-001 and DFM-012 on every muscle strip package, because all of them are 300 um thick with no declared transport and none carries a licensing block. DFM-009 in addition on muscle-strip-designed.wwd, graded-strip.wwd, bioprinted-strip.wwd and pinwheel-study.wwd, which carry a critical response criterion and no yield block. DFM-010 on pinwheel-study.wwd, once per component with no validity window. On neurontile-asbuilt.wwd, DFM-012 twice: the glutamatergic neuron entry declares rights unknown, and the astrocyte entry carries no licensing block.

Do design rules run on measured results?

One does. DFM-009 reads the yield block of the results document and reports critical response criteria that have no yield statement. The remaining rules read the design document: component kind, dimensions, fields, interfaces, biology, shipping and validity window, and the acceptance criteria the design declares.

Continue

Related pages.