Invention, use, and technology diffusion

This tutorial follows one technique from a workshop trial to local adoption and teaching, using the canwu-technology technology simulation extension. You will learn the records it uses in place of a global tech tree, how the shared evaluator judges trials and uses from data, and where the optional historical research plugins fit. For the full record model and validation rules, see Technology.

Open technology_diffusion.rs

Browse the technology extension

Run it

From the repository root:

cargo run -p canwu-technology --example technology_diffusion

adoption=Committed, scale=10, learner_knowledge=0 (opportunity is not automatic learning)
snapshot restore and exact replay match

The workshop’s adoption is committed at scale 10. The learner’s knowledge count is 0: opening an apprenticeship creates a chance to learn, and the learning itself needs its own records. The second line confirms that a restored snapshot and an exact replay both match the live run.

One record per step

canwu-technology stores each stage of technical change as its own record, which can be saved, disputed, and replayed:

Stage	Record	What it establishes
Design	`TechniqueSpec`, `TechniqueRevision`	What the technique does, its requirement groups, and one immutable recipe or design. A change creates a new revision that names its parents.
Work	`TechnicalProgram`	A holder’s research, adaptation, or training effort at a site.
Trial	`ExperimentAttempt`, `ProductionRun`, `AttemptObservation`	One result under stated conditions, returned by an authorized provider.
Skill	`CapabilityQualification`	A holder can perform an operation at a site, backed by evidence that meets the technique’s qualification rule.
Installation	`ImplementationRecord`	Equipment installed at a site, with capacity and reliability.
Use	`ApplicationSpec`, `AdoptionRecord`	One site adopts the technique for one use after a viability check.
Spread	`TransmissionOpportunity`	A chance to learn through documents, demonstration, apprenticeship, artifact inspection, personnel transfer, or independent investigation.

Your game owns resources, characters, economics, information artifacts, and narrative. The extension owns bounded, deterministic, validated technology state. Labor, capital, fuel, institutional resistance, and political support belong in your content and game rules.

How the example works

Rendering diagram…

View diagram source

flowchart LR
  Program["TechnicalProgram"] --> Intent["TechnologyExecutionIntent<br/>authorize a trial"]
  Intent --> Attempt["ExperimentAttempt<br/>provider result"]
  Attempt --> Qual["CapabilityQualification"]
  Qual --> Impl["ImplementationRecord"]
  Impl --> Adopt["AdoptionRecord<br/>one use"]
  Impl --> Teach["TransmissionOpportunity<br/>apprenticeship"]
  Teach --> Learner["Learner's<br/>TechnicalProgram"]

main in technology_diffusion.rs is written as one linear sequence so each step is visible.

Catalog. scenario() loads the catalog as initial-scenario records: two MetricSchemas (reliability in per mille and fuel cost), a TechniqueSpec that requires reliability of at least 700, a TechniqueRevision evaluated by REFERENCE_EVALUATOR_V1, and an ApplicationSpec, “drain a deep working”, that is viable when fuel cost is at most 500.
Program. The operator starts a TechnicalProgram with the tracked command apply_technology_operation_v1. The helper apply_command enqueues the command and settles two boundaries: the first admits it, the second applies the change.
Trial. The operator authorizes a TechnologyExecutionIntent for the provider reference-lab. The provider returns an ExperimentAttempt for that exact intent through the technology_result_v1 ingress, with reliability 820. A second provider, meter-reader, records an AttemptObservation of fuel cost 400 for the same attempt.
Qualification and installation. A command creates the CapabilityQualification, citing the attempt, then the ImplementationRecord, citing the qualification.
Adoption. evaluate_application checks the fuel cost against the use’s viability rule. The AdoptionRecord is created with status Committed and scale 10, citing the installation and the fuel observation.
Teaching. The learner opens a training program at another site, and the operator opens an apprenticeship TransmissionOpportunity that cites the installation as source_capability and links the learner’s program.
Restore and replay. from_technology_snapshot_json and replay_technology_from_journal rebuild the runtime, and the example asserts both match.

Rules the records enforce

A trial counts only after authorization. Provider requirements of the program are checked when the result arrives, so an unsuitable provider can hold a pending intent and then have its result rejected.
Every qualification cites distinct attempts that match its technique revision, operation, and site, and in which its holder took part. Its recorded reliability must equal the share of those attempts that passed. An active qualification must also meet the minimums of the configured QualificationRule; an inactive one does not have to.
A new installation cites a current, active qualification and its assets. A trial, committed, or recommitted adoption cites current, active installations. Older exact versions remain history and grant nothing new.
A new practice transmission cites the exact qualification or installation that is valid and current at that boundary. Deactivating the source later blocks new transmissions and leaves existing opportunities in place. An existing opportunity can only close; to resume, open a new opportunity from a source valid at that time.
A teacher outside the simulated world is cited as an external transmission source (ExternalTransmissionSourceV1): an initial-scenario content record owned outside canwu.technology, with a declared reliability. Demonstration, apprenticeship, and personnel-transfer opportunities cite exactly one of source_capability and external_source. An external source has no holder or site in the simulation, so the destination opens the opportunity.
Actors learn about a new TechniqueRevision through observation, technical claims, or transmission; creating the revision adds nothing to anyone’s knowledge.

Relationships that must keep their meaning after a record changes use an exact domain-record version. DomainRecordVersionRef fixes the record, the version, and the evidence that established it. If an installation is later deactivated, an adoption still reads the installation version it cited.

One evaluator for every technology

The reference evaluator reads metrics and thresholds from data. Technology names such as “papermaking”, “gunpowder”, or “steam engine” appear only in content.

let result = evaluate_attempt(
    &technique_revision,
    &technique_spec,
    &metric_schemas,
    &MetricContext {
        values: local_measurements,
    },
)?;

if result.passed {
    // Evidence for this trial only. Qualification, installation,
    // and adoption each need their own authorized operation.
}

A technique’s requirement groups must all pass (AND); inside a group, any one threshold is enough (OR). Every value has a unit and an integer scale, so snapshots, forks, and exact replay produce the same result on every run.

Five technologies, one contract

The repository tests check that the same contract produces these counterfactuals:

Case	Counterfactual
Papermaking	Local fiber and operator evidence can each reverse the result of the same process.
Woodblock printing	A stable long edition passes its use criteria; a frequently changed short edition fails.
Movable type	Glyph stock, composition labor, edition size, and text changes reverse its fit relative to woodblock.
Gunpowder	The same weak powder passes a visible-flame use and fails propulsion.
Steam engine	Pumping with cheap fuel passes; costly pumping and low-torque rotary use fail.

five_technology_profiles_use_one_evaluator_contract runs each technology through catalog loading, an authorized program command, result ingress, boundary settlement, and a state query. historical_profiles_reverse_outcomes_without_case_specific_solver_code checks the counterfactuals with evaluate_attempt() and evaluate_application(). Run both with:

cargo test -p canwu-technology --test framework

Optional historical research plugins

Detailed historical interpretation lives in canwu-history-research, outside the simulation core, and leaves base technology records unchanged. It provides three historical research plugins that you can enable separately:

Plugin	Records assessments of
`HistoricalSourcesPlugin`	A source’s dating, authenticity, reliability, and provenance
`HistoricalPracticePlugin`	Practitioners, workshops, practice relationships, notebook summaries, and negative results
`ProductionArchaeologyPlugin`	Remains, samples, dates, and production-process hypotheses

Each plugin stores assessments only; the source artifacts, base attempts, and runtime assets they discuss keep their own records. Every assessment records its assessor, method and version, as-of time, uncertainty, summary digest, and citations that existed no later than the as-of time. A contradiction or supersession may target only an earlier assessment of the same exact subject. A citation proves that the source exists; its relevance and truth remain the assessor’s claim.

Assessment commands are trusted-host input. If your players must first gain access to the information, enforce that in your own research-workflow plugin before you submit the command. HistoricalAnalysis is a read-only host query. Enable no plugin, one, or all three through HistoricalResearchSuite.

Limits

The technology extension and each history plugin enforce their own per-boundary and total limits; an over-budget boundary rejects its new operations and later boundaries continue. Technology lists every limit.

The home-hardware benchmark records how this workload performed on an earlier engine version; measure again with your own renderer, assets, and other monthly systems running.

Read the home-hardware evidence

Browse the historical research plugins