Package 'delphyr'

Description

Accept an invitation after verified login and an explicit confirmed action

Usage

accept_panel_invitation(
  repo,
  actor,
  study_id,
  invitation_id,
  token,
  confirmed,
  command_id
)

Arguments

Value

Invitation, membership and pseudonym receipt. No consent or round enrollment is created. Existing provisioned accounts are required.

Description

Register a synthetic panel member

Usage

add_panelist(repo, actor, study_id, principal_id, group_code, command_id)

Arguments

Value

Study-specific pseudonym. A completed study refuses new members with DEL_CONFLICT (path study.state).

Description

Existing rounds and snapshots retain their exact protocol. An amendment never changes the meaning of an existing scale code. Introduce a new scale code for changed scales and a new item version before using it. This service records a synthetic technical approval, not institutional or ethical approval.

Usage

amend_protocol(
  repo,
  actor,
  study_id,
  protocol,
  expected_hash,
  reason,
  command_id
)

Arguments

Value

New protocol id, version and hash.

Description

Analyse a frozen round independently of the application

Usage

analyse_round(snapshot, rules = snapshot$protocol$analysis$consensus)

Arguments

Value

delphyr_analysis containing results, denominators, missingness, distributions, settings, warnings and scientific provenance.

Examples

summary(analyse_round(demo_snapshot()))

Description

Assign released feedback to an unopened subsequent round

Usage

assign_feedback(repo, actor, round_id, feedback_id, command_id)

Arguments

Value

Target round UUID. A round shows one feedback: a second assignment, of the same or of another feedback, is refused with DEL_CONFLICT (path feedback.assigned). A retry under the same key returns the receipt.

Description

This adapter does not implement OIDC or verify browser credentials. It accepts only the transport and headers established by the separately configured, isolated authentication gateway. A header alone is not authentication.

Usage

authenticated_actor(repo, request, config)

Arguments

Value

Short-lived delphyr_actor. Unknown, disabled, spoofed or missing identities fail closed with DEL_UNAUTHORIZED. No account is auto-provisioned.

Examples

if (FALSE) {
  config <- new_authentication_config(
    "https://identity.example/realms/study",
    Sys.getenv("DELPHYR_GATEWAY_SECRET"), "127.0.0.1"
  )
  # In a trusted session factory: authenticated_actor(repo, session$request, config)
}

Description

Cancel remaining synthetic campaign delivery

Usage

cancel_campaign(repo, actor, campaign_id, reason, command_id)

Arguments

Value

Campaign UUID; already recorded sink receipts remain immutable. A campaign that is already cancelled is refused as 'campaign.state'.

Description

The deadline is not part of the reviewed instrument, so the approval of a round stays valid. Before a round opens the deadline may be any future time. Once the round is open it can only be moved to a later time: nobody loses time they were told they had. An open round whose deadline has passed accepts answers again after an extension. A closed round is never reopened this way. The change is recorded with its rationale in the round's history and in the audit trail.

Usage

change_round_deadline(
  repo,
  actor,
  round_id,
  deadline,
  expected_hash,
  reason,
  command_id
)

Arguments

Value

Round id and the new deadline in UTC.

Description

Claim one available durable job with an exclusive lease

Usage

claim_job(repo, lease_seconds = 120, study_id = NULL)

Arguments

Value

Claimed row or empty data frame. Worker infrastructure API.

Description

Classify consensus from explicit counts

Usage

classify_consensus(counts, rule)

Arguments

Value

Classification and unrounded proportions with numerator and denominator.

Examples

classify_consensus(
  list(n_valid = 10, n_agree = 7, n_disagree = 1),
  demo_protocol()$analysis$consensus
)

Description

Append a reasoned theme coding decision

Usage

code_qualitative_source(
  repo,
  actor,
  study_id,
  source_id,
  theme_id,
  decision,
  reason,
  command_id
)

Arguments

Value

Coding-event UUID. Counts represent decisions, not unique people.

Description

Compare paired responses across compatible rounds

Usage

compare_rounds(previous, current, mapping = NULL)

Arguments

Value

delphyr_comparison table, reporting attrition and unpaired means separately.

Examples

compare_rounds(demo_snapshot(c(5, 7, 8, 9)), demo_snapshot(c(6, 7, 7, 9)))

Description

Complete a study after finalization and explicit item decisions

Usage

complete_study(repo, actor, study_id, reason, command_id)

Arguments

Value

Completed study UUID.

Description

Connect to an explicitly configured PostgreSQL database

Usage

connect_repository(
  ...,
  environment = c("development", "test"),
  artifact_root = tempfile("delphyr-artifacts-")
)

Arguments

Value

A delphyr repository. Close its connection with DBI::dbDisconnect(repo$con).

Description

Canonical scientific content hash

Usage

content_hash(x, version = "2")

Arguments

Value

SHA-256 string of sorted UTF-8 JSON, excluding no fields implicitly. Version 2 starts with 'v2:'; legacy version 1 is an unprefixed digest. A legacy hash cannot detect changes below its original numeric precision.

Examples

content_hash(list(b = 2, a = 1))

Description

Qualitative content enters participant feedback only as an editorial version that another person has released. The service reads the released text itself; text supplied by the caller is not accepted. A version whose source is linked to item codes is shown beside those items.

Usage

create_feedback(
  repo,
  actor,
  analysis_id,
  qualitative = list(),
  command_id,
  released_edits = character()
)

Arguments

Value

Feedback UUID and hash, requiring separate release.

Description

Define an immutable version of a qualitative theme

Usage

create_qualitative_theme(
  repo,
  actor,
  study_id,
  code,
  version,
  label,
  definition,
  command_id
)

Arguments

Value

Theme UUID.

Description

Create an isolated synthetic study and its first immutable protocol

Usage

create_study(repo, actor, protocol, command_id)

Arguments

Value

Study id and protocol id.

Description

Structured delphyr error

Usage

del_abort(code, path = "")

Arguments

Value

Does not return; signals a structured error.

Examples

tryCatch(del_abort("DEL_VALIDATION", "scale"), error = function(e) e$code)

Description

Create a short-lived, server-side demo actor

Usage

demo_actor(repo, principal_id, lifetime_seconds = 3600)

Arguments

Value

Actor context for trusted server code, never accepted from browser payloads.

Description

Synthetic protocol example

Usage

demo_protocol()

Value

Complete demo configuration; thresholds are examples, not recommendations.

Examples

validate_protocol(demo_protocol())$valid

Description

Synthetic offline snapshot

Usage

demo_snapshot(
  values = c(1, 4, 6, 7, 7, 8, 8, 9, 9, 9),
  groups = rep("professionals", length(values))
)

Arguments

Value

Validated synthetic snapshot.

Examples

analyse_round(demo_snapshot())$results

Description

Create a synthetic two-group development study

Usage

demo_study(
  repo,
  n = 30L,
  item_count = 12L,
  code = paste0("DEMO-", substr(uid(), 1, 8))
)

Arguments

Value

Manager and panel actors, study/consent ids and unapproved round.

Description

Resolve a private artifact only after a fresh rights check

Usage

download_artifact(repo, actor, artifact_id)

Arguments

Value

Private directory path for trusted server download code. An export whose worker stopped after registering it but before giving it its final name is delivered from its temporary name, '<id>.partial'.

Description

Applies the round's protocol entry policy and each member's current stakeholder group. Enrollment, withdrawal and group changes of one study take effect one after the other: a member who withdraws meanwhile is either not enrolled or enrolled and withdrawn. Enrollment is possible until the round closes. Feedback already assigned to an unopened round is assigned to the new enrollments as well; an open round with assigned feedback accepts no further enrollment, so that everyone rating in a round has the same information.

Usage

enroll_panel(repo, actor, round_id, command_id)

Arguments

Value

Round UUID and the number of enrollments added.

Description

Freeze the exact submitted revision set of a closed round

Usage

freeze_round(repo, actor, round_id, command_id)

Arguments

Value

Immutable snapshot UUID and content hash.

Description

Rights of the signed-in account outside any study

Usage

get_account_rights(repo, actor)

Arguments

Value

List with can_create_study. Creating a study is granted by the operator to an account, never chosen in the interface.

Description

Read a persisted aggregate analysis

Usage

get_analysis(repo, actor, analysis_id)

Arguments

Value

delphyr_analysis.

Description

Read current study capabilities

Usage

get_capabilities(repo, actor, study_id)

Arguments

Value

Character vector; this UI hint does not replace service authorization.

Description

Read released aggregate feedback plus only the actor's prior answers

Usage

get_feedback(repo, actor, enrollment_id)

Arguments

Value

Aggregate feedback, own prior response table, the comparability decisions for revised items that were in force when the target round opened, the released qualitative content and, where the feedback was corrected, the note for participants; or NULL.

Description

Preview the exact reviewed feedback artifact before release

Usage

get_feedback_candidate(repo, actor, feedback_id)

Arguments

Value

Content, hash and state of the candidate.

Description

Read the comparability decisions of a study

Usage

get_item_comparability(repo, actor, study_id)

Arguments

Value

Decision history; effective marks the latest decision per version pair.

Description

Retrieve an authorized operation state

Usage

get_operation(repo, actor, operation_id)

Arguments

Value

State, result reference and safe error code.

Description

Operational status of a study's background work

Usage

get_operations_status(repo, actor, study_id)

Arguments

Value

Counts of jobs by type and state with the age of the oldest waiting job, counts of messages by delivery state with the age of the oldest waiting message, and the number of uncertain deliveries. No content.

Description

Retrieve a minimal panel import receipt through current coordination rights

Usage

get_panel_import_receipt(repo, actor, receipt_id)

Arguments

Value

Receipt metadata and invitation IDs without contact values.

Description

Read restricted qualitative provenance or reviewed export tables

Usage

get_qualitative_provenance(repo, actor, study_id, export = FALSE)

Arguments

Value

Named tables with explicit source, coding, item and review provenance. These are restricted research records, not participant feedback.

Description

Retrieve only the actor's current questionnaire and consent information

Usage

get_questionnaire(repo, actor, enrollment_id)

Arguments

Value

Instrument, own responses, receipt and required consent information.

Description

Lists each class of stored data with its count and the age of its oldest and newest record. With 'periods', a proposed number of days per class, it also states how many records would be older than that period. It is a dry run: nothing is deleted, and the software ships no retention periods. A period is the decision of the responsible organisation.

Usage

get_retention_report(repo, actor, study_id, periods = NULL)

Arguments

Value

A table with data_class, records, oldest, newest, period_days and older_than_period.

Description

Read the exact instrument of a round for review

Usage

get_round_instrument(repo, actor, round_id)

Arguments

Value

Round number, state, deadline, content hash, protocol version, study information and every item with all approved language versions. Contains no panel identities or responses.

Description

Reports every finding at once instead of failing on the first. Errors block the transition; warnings describe a foreseeable methodological consequence, such as a required group below the minimum valid n, and leave the decision to the study team.

Usage

get_round_readiness(repo, actor, round_id)

Arguments

Value

delphyr_validation: valid, issues (severity, code, path, message_key, details) and schema_version. Approval ignores the deadline_passed and no_enrollments findings; opening requires none.

Description

Retrieve a frozen snapshot through current study authorization

Usage

get_snapshot(repo, actor, snapshot_id)

Arguments

Value

Validated delphyr_snapshot.

Description

Read the current study documentation and its version history

Usage

get_study_documentation(repo, actor, study_id)

Arguments

Value

Current version, hash and fields; a topic table that marks every reporting topic documented or not documented; and the version history.

Description

Analysts read it as well: the protocol holds the rules and the time zone of the analyses they work with.

Usage

get_study_setup(repo, actor, study_id)

Arguments

Value

Protocol and published information versions, without panel identities.

Description

For monitoring and the first look at an incident. The result holds counts and ages only: no study content, contact, account or study identifier. 'ready' is TRUE when the database answers and its schema is exactly the one this software version ships. 'attention' lists what a person should look at; it does not make the application unready. A database whose schema is not the one of this software, for example one of the previous release, is reported with its schema state alone: the tables of later migrations may not exist there yet. 'artifacts' counts exports that can be downloaded, expired ones whose files were not yet removed, removed ones, and 'unfinished': directories in the private export directory of 'repo' that no registration covers, left by a stopped worker or an earlier release (see remove_unfinished_exports()).

Usage

get_system_status(
  repo,
  path = system.file("sql", package = "delphyr"),
  heartbeat_seconds = 60L
)

Arguments

Value

A list with 'ready', 'schema', 'workers', 'jobs', 'messages', 'artifacts' and 'attention'; only 'ready', 'schema' and 'attention' when the schema is not current or the database does not answer.

Description

After a database was restored from a backup, a message that was waiting when the backup was taken may have been delivered before the loss. This function turns every message that is queued or in flight into an uncertain delivery with the cause 'restored_from_backup'. The worker then sends none of them, and a coordinator decides for each one in the interface: delivery confirmed, send again, or abandon. Run it before the worker is started on a restored database. Without 'dry_run = FALSE' it changes nothing.

Usage

hold_pending_messages(repo, dry_run = TRUE, study_id = NULL)

Arguments

Value

A list with the numbers of messages 'queued' and 'in_flight' that were found and the number 'held', which is zero for a dry run.

Description

Atomically import exactly reviewed synthetic contacts as unbound drafts

Usage

import_panel(repo, actor, study_id, preview, expected_hash, reason, command_id)

Arguments

Value

Receipt id, file/preview hashes, counts and opaque invitation-draft IDs.

Description

Every submitted free-text answer of the snapshot becomes one immutable original source, referenced by round, item and an opaque suffix. The sources carry no pseudonym; editorial work, redaction and independent release follow as for any other source. Answers that already have a source are skipped, so the import can be repeated.

Usage

import_round_contributions(repo, actor, snapshot_id, command_id)

Arguments

Value

Snapshot UUID and the number of sources created.

Description

The code combines the study, invitation and private token so that the invited person enters one value after verified login. Treat the whole code as secret.

Usage

invitation_code(study_id, invitation_id, token)

Arguments

Value

A single private string with redacted printing; as.character() reveals it.

Description

Issue a synthetic invitation for an explicitly approved existing account

Usage

issue_panel_invitation(
  repo,
  actor,
  study_id,
  draft_id,
  principal_id,
  token,
  ttl_seconds = 900L,
  reason,
  command_id
)

Arguments

Value

Invitation UUID and expiry, without the token or contact fields.

Description

Link an imported or proposed item version to its original source

Usage

link_item_source(
  repo,
  actor,
  study_id,
  item_code,
  item_version,
  source_id,
  reason,
  command_id
)

Arguments

Value

Source-link UUID. This does not import or approve an instrument item.

Description

Every event names time, action, object and actor, with the recorded rationale where the action required one. Staff are referenced by their account UUID. Panel actions carry no account reference, and worker events reference the person who approved the work.

Usage

list_audit_events(
  repo,
  actor,
  study_id,
  from = NULL,
  to = NULL,
  actions = NULL,
  limit = 500L
)

Arguments

Value

Data frame occurred_at, action, detail, object_ref, reason, actor_kind (staff, panel or worker) and actor_ref.

Description

Preview eligible campaign selection fields without contacts or answers

Usage

list_campaign_enrollments(repo, actor, round_id)

Arguments

Value

Enrollment UUID, study pseudonym, participation state and the number of approved reminders that count against the protocol's limit, including reminders delivered before their campaign was cancelled.

Description

List rounds available to a campaign coordinator

Usage

list_campaign_rounds(repo, actor, study_id)

Arguments

Value

Minimal round identifiers, numbers and states.

Description

List frozen rounds with free-text contributions

Usage

list_contribution_rounds(repo, actor, study_id)

Arguments

Value

Round number, snapshot UUID and the number of submitted free-text answers, with how many are already preserved as qualitative sources.

Description

Lists only rounds that were opened. A round that is still being prepared, reviewed or approved, or that was withdrawn, is not shown to panel members, and its instrument cannot be read through any panel service.

Usage

list_enrollments(repo, actor, study_id)

Arguments

Value

Enrollment table.

Description

List the human item decisions of a study

Usage

list_item_decisions(repo, actor, study_id)

Arguments

Value

Round number, item, disposition, rationale and time of each decision.

Description

List the panel of a study by pseudonym

Usage

list_panel(repo, actor, study_id)

Arguments

Value

Study pseudonym, stakeholder group, whether the member is active or withdrew, and counts of rounds enrolled and submitted. No account references, contacts or responses.

Description

List imported invitation drafts and their current invitation state

Usage

list_panel_invitations(repo, actor, study_id)

Arguments

Value

One row per draft: source reference, display name, group, locale, latest invitation id, expiry and state (unbound, outstanding, expired, revoked or accepted). Never contains tokens, hashes, emails or pseudonyms.

Description

Read the immutable study protocol history

Usage

list_protocol_versions(repo, actor, study_id)

Arguments

Value

Version table with content hashes, configurations and amendment reasons.

Description

List exact redacted versions for independent management review

Usage

list_qualitative_reviews(repo, actor, study_id)

Arguments

Value

Reviewed content candidates and release state; excludes originals.

Description

List released editorial versions available for participant feedback

Usage

list_released_edits(repo, actor, study_id)

Arguments

Value

Edit UUID, source reference, kind, released text, release time and the item codes linked to the source. Originals are not included.

Description

Read the released feedback of a round and its corrections

Usage

list_released_feedback(repo, actor, study_id)

Arguments

Value

One row per released feedback: round, UUID, hash, the round it is assigned to and, where it was corrected, its replacement with rationale.

Description

List study round states and frozen result references

Usage

list_rounds(repo, actor, study_id)

Arguments

Value

Round table.

Description

List studies available to the current actor

Usage

list_studies(repo, actor)

Arguments

Value

Study table without contacts or response data.

Description

List study staff and their current rights

Usage

list_study_staff(repo, actor, study_id)

Arguments

Value

One row per staff account: principal UUID, issuer, subject, whether the account and membership are active, and granted and revoked rights. Panel membership is not part of this list.

Description

List deliveries whose outcome is uncertain

Usage

list_uncertain_deliveries(repo, actor, study_id)

Arguments

Value

Message UUID, campaign kind, round number, study pseudonym, the cause, the adapter and the time of the uncertain attempt.

Description

An entry holds the time, a correlation ID, the component, the operation, its duration and, for a refused or failed operation, the condition class and field path. Arguments, results, condition messages, account references and request headers are never written.

Usage

log_event(
  operation,
  error = NULL,
  correlation_id = new_correlation_id(),
  component = "service",
  duration_ms = NULL,
  reference = NULL
)

Arguments

Details

Entries are written to standard error as one JSON object per line. Set 'options(delphyr.log_sink = function(line) ...)' to route them elsewhere. 'options(delphyr.log_level = )' or the environment variable 'DELPHYR_LOG_LEVEL' selects 'off', 'error' (failures), 'warning' (refusals and failures; the default) or 'info' (every operation).

Value

The correlation ID, invisibly.

Examples

options(delphyr.log_sink = function(line) NULL)
log_event("example", error = simpleError("not written"))
options(delphyr.log_sink = NULL)

Description

Measures the operation and writes one entry, see log_event(). A refused or failed operation signals its original condition again, extended by the field 'correlation_id', so that the message shown to a person can quote it.

Usage

log_operation(
  operation,
  code,
  correlation_id = new_correlation_id(),
  component = "service"
)

Arguments

Value

The value of code().

Examples

options(delphyr.log_sink = function(line) NULL)
log_operation("example", function() 1 + 1)
options(delphyr.log_sink = NULL)

Description

Apply checksummed forward migrations

Usage

migrate_repository(repo, path = system.file("sql", package = "delphyr"))

Arguments

Value

Invisibly TRUE. Changed historical migration files are rejected.

Description

Configure the trusted authentication gateway boundary

Usage

new_authentication_config(
  issuer,
  gateway_secret,
  trusted_proxy_addresses,
  max_session_seconds = 900L
)

Arguments

Value

Server-only delphyr_authentication_config. Never serialize to a browser.

Description

The ID is random. It is derived from no account, study or content and can be shown to a person and quoted in a support request.

Usage

new_correlation_id()

Value

Twelve lowercase hexadecimal characters.

Examples

new_correlation_id()

Description

Generate a private synthetic invitation token

Usage

new_invitation_token()

Value

A 256-bit secret with redacted printing. Retain privately; only its hash is persisted. Never put the token in logs, audit records or research exports.

Description

The contract for a delivery provider. 'send' receives one message as a list with message_id, idempotency_key, kind, locale, subject, body, to and display_name, and must return 'list(status = "accepted", provider_ref = )', 'list(status = "rejected", reason = )' for a permanent refusal or 'list(status = "retry", reason = )' for a transient failure. The same idempotency key is passed on every attempt for a message. An error, a timeout or any other return value leaves the delivery uncertain; it is then never repeated automatically. No production adapter is shipped or approved: contact addresses are restricted to the reserved '.invalid' domain.

Usage

new_message_adapter(name, send)

Arguments

Value

A delphyr_message_adapter for process_campaign_message().

Description

Construct a protocol

Usage

new_protocol(config)

Arguments

Value

delphyr_protocol; invalid inputs raise DEL_VALIDATION.

Examples

new_protocol(demo_protocol())$schema_version

Description

Construct a validated response scale

Usage

new_scale(
  type,
  levels = integer(),
  labels = as.character(levels),
  missing_options = c("unable_to_judge", "abstained")
)

Arguments

Value

A delphyr_scale. Invalid input raises DEL_VALIDATION.

Examples

new_scale("ordinal_integer", 1:9, as.character(1:9))

Description

Construct an immutable analysis input

Usage

new_snapshot(
  responses,
  assignments,
  items,
  protocol,
  round_number = 1L,
  snapshot_id = NULL,
  hash_version = "2"
)

Arguments

Value

delphyr_snapshot, with all assigned fields materialized, including missingness.

Examples

s <- demo_snapshot()
s$content_hash

Description

Decode an invitation hand-over code

Usage

parse_invitation_code(code)

Arguments

Value

List study_id, invitation_id and token; DEL_UNAUTHORIZED when malformed.

Description

Prepare an exact synthetic communication campaign

Usage

prepare_campaign(
  repo,
  actor,
  round_id,
  enrollment_ids,
  kind,
  subject,
  body,
  locale = "en",
  template_version = 1L,
  command_id
)

Arguments

Value

Campaign id, exact content/recipient hash and recipient count.

Description

Prepare disclosure-controlled feedback

Usage

prepare_feedback(
  analysis,
  qualitative = list(),
  policy = list(group_statistics = FALSE, minimum_display_cell_n = 5L,
    complementary_suppression = TRUE)
)

Arguments

Value

delphyr_feedback_draft. Suppressed data are removed, not hidden in markup.

Examples

prepare_feedback(analyse_round(demo_snapshot()))$hash

Description

Prepare an authorized aggregate report and numeric export supplement

Usage

prepare_report_data(repo, actor, snapshot_id)

Arguments

Value

A delphyr_report_data with allowlisted tables and a content hash.

Description

Prepare a frozen-instrument candidate and enroll active panelists

Usage

prepare_round(
  repo,
  actor,
  study_id,
  items,
  consent_version_id,
  deadline,
  command_id
)

Arguments

Value

Round UUID and exact instrument hash.

Description

Covers every frozen round: design, protocol versions, recruitment and participation, instruments, results, comparisons between rounds, human decisions, lineage, released feedback, final items and the author-supplied documentation. Topics without an entry stay marked "not documented".

Usage

prepare_study_report_data(repo, actor, study_id, profile = "study_summary")

Arguments

Value

A delphyr_report_data with a content hash, for render_study_report().

Description

Preview exact campaign text and pseudonymous recipients

Usage

preview_campaign(repo, actor, campaign_id)

Arguments

Value

Plain text, hash, the study's reminder rules, the approved send window, pseudonyms and delivery states; no contacts or answers.

Description

Preview a synthetic panel CSV with blocking duplicate review

Usage

preview_panel_import(
  repo,
  actor,
  study_id,
  csv,
  schema_version = "1.0",
  delimiter = ","
)

Arguments

Value

Restricted preview with rows, row/column issues, exact file hash and approval hash.

Description

Preview an invitation without creating membership or consuming its token

Usage

preview_panel_invitation(repo, actor, study_id, invitation_id, token)

Arguments

Value

Study title and invitation expiry only, for the exact approved account.

Description

Claim, eligibility check and result are separate short transactions; no database transaction is held while the provider is called. Immediately before sending, the worker rechecks cancellation, approval authority, participation, consent, submission and round state, which can only reduce the approved audience. A transient failure is retried with a growing delay up to three attempts.

Usage

process_campaign_message(
  repo,
  adapter = sink_adapter(),
  study_id = NULL,
  lease_seconds = 30L
)

Arguments

Value

FALSE when idle, or message id, state and reason.

Description

Process one approved message into a local database sink

Usage

process_campaign_sink(repo, study_id = NULL, lease_seconds = 30L)

Arguments

Value

FALSE when idle or a message id/state/reason. Never sends external mail.

Description

Provision a synthetic development principal

Usage

provision_demo_principal(repo, subject, can_create = FALSE)

Arguments

Value

Principal UUID. This is not a production authentication adapter.

Description

Publish immutable synthetic study information

Usage

publish_consent(repo, actor, study_id, text, locale, command_id)

Arguments

Value

Consent version id. A completed study refuses new versions with DEL_CONFLICT (path study.state).

Description

Reads a UTF-8 CSV item file. Every value is read as text, so codes keep their leading zeros and a text such as "NA" stays text. Required columns are 'item_code', 'item_version', 'locale', 'text', 'dimension_code', 'scale_code', 'source_ref', 'required' and 'display_order'. This differs from the v1 item import contract of the specification in two ways: 'item_version' is an additional column, because a version names the rated wording across rounds, and 'source_ref' is required, not optional. A file that lacks either column is refused, as is the specification's v1 example, which has no 'item_version'. 'item_version' and 'display_order' must be written as whole numbers and 'required' as true or false. The optional columns 'definition' and 'domain_code' are accepted and not stored. Check the result with validate_items() before preparing a round.

Usage

read_item_import(file, delimiter = ",")

Arguments

Value

Data frame for validate_items() and prepare_round(). A file that does not follow the contract is refused with DEL_VALIDATION, path items.file, items.encoding, items.columns, items.rows or the column of the first value that is not of its type, such as items.display_order.

Description

Record an explicit consent decision

Usage

record_consent(repo, actor, study_id, consent_version_id, decision, command_id)

Arguments

Value

Consent event id.

Description

A changed item version interrupts paired comparison by default. This records the study team's explicit decision for one version pair, with its rationale. A later decision for the same pair supersedes the earlier one; the history is kept and exported.

Usage

record_item_comparability(
  repo,
  actor,
  study_id,
  item_code,
  dimension_code,
  previous_version,
  current_version,
  comparable,
  reason,
  command_id
)

Arguments

Value

Decision UUID.

Description

Record a human decision separately from analytic classification

Usage

record_item_decision(
  repo,
  actor,
  analysis_id,
  item_code,
  disposition,
  reason,
  command_id
)

Arguments

Value

Decision UUID. A completed study refuses new decisions with DEL_CONFLICT (path study.state).

Description

Record a complete item split or merge without deleting its parents

Usage

record_item_lineage(
  repo,
  actor,
  study_id,
  parents,
  children,
  relation,
  reason,
  command_id
)

Arguments

Value

Lineage-event UUID and hash. Child codes are new semantic identities.

Description

Preserve an original synthetic qualitative contribution

Usage

record_qualitative_source(
  repo,
  actor,
  study_id,
  text,
  source_ref,
  command_id,
  response_revision_id = NULL
)

Arguments

Value

Source UUID and content hash. This is restricted editorial data.

Description

Reports never invent authorship, funding, conflicts of interest, approvals, interpretation or deviations. Study staff record these statements here; each change is a new immutable version, and topics without an entry stay marked "not documented". Recording a reference to an approval does not grant one.

Usage

record_study_documentation(
  repo,
  actor,
  study_id,
  fields,
  expected_version,
  reason,
  command_id
)

Arguments

Value

Documentation id, version and content hash.

Description

Record that a worker process is alive

Usage

record_worker_heartbeat(repo, worker_id, started = FALSE)

Arguments

Value

Invisibly TRUE.

Description

Create a separate redacted qualitative version

Usage

redact_qualitative_source(
  repo,
  actor,
  study_id,
  source_id,
  text,
  reason,
  command_id,
  kind = "redaction"
)

Arguments

Value

Edit UUID and exact hash, requiring independent release.

Description

Account onboarding is an explicit coordinator decision. The stable issuer and subject come from the institution's identity provider, never from an email address. The registered principal has no study rights until its own invitation is accepted. Existing disabled accounts are not reactivated.

Usage

register_invited_account(
  repo,
  actor,
  study_id,
  issuer,
  subject,
  reason,
  command_id
)

Arguments

Value

Principal UUID for issue_panel_invitation(); no rights are granted.

Description

Rights are granted to an exact issuer and subject, never to an email address. An account of a verified gateway issuer (an http or https URL) is registered if it does not exist yet; any other issuer, such as synthetic development accounts, must already be provisioned. The account receives no right by this step. A disabled account is not reactivated.

Usage

register_staff_account(
  repo,
  actor,
  study_id,
  issuer,
  subject,
  reason,
  command_id
)

Arguments

Value

Principal UUID for set_capability().

Description

The approval covers the exact text, the exact recipients and the earliest send time. Quiet hours of the protocol are fixed with the approval. A reminder is refused when any recipient would exceed the protocol's maximum number of reminders or receive it sooner than the minimum interval after the previous one; the limits never shrink an approved audience silently. Approvals of reminders for one round are decided one at a time. The worker keeps the interval as well: a reminder that would reach a person sooner after the previous one, because quiet hours or a stopped worker held both, waits until the interval has passed.

Usage

release_campaign(
  repo,
  actor,
  campaign_id,
  expected_hash,
  reason,
  command_id,
  not_before = NULL
)

Arguments

Value

Campaign id, approved recipient count and the approved earliest send time. No message is sent.

Description

Release an exact reviewed feedback candidate

Usage

release_feedback(repo, actor, feedback_id, expected_hash, command_id)

Arguments

Value

Feedback UUID.

Description

Released feedback is never edited. A correction releases a second feedback candidate of the same analysis and records that it replaces the first: later views show the corrected version with the note for participants, while earlier display events keep referring to the version that was shown.

Usage

release_feedback_correction(
  repo,
  actor,
  feedback_id,
  replacement_id,
  expected_hash,
  reason,
  impact_note,
  participant_note,
  command_id
)

Arguments

Value

The replacement feedback UUID and the feedback it replaces.

Description

Release an exact qualitative version after independent review

Usage

release_qualitative_edit(
  repo,
  actor,
  study_id,
  edit_id,
  expected_hash,
  reason,
  command_id
)

Arguments

Value

Immutable release UUID and content hash.

Description

An export is a temporary private copy of data that stays in the database. After 'expires_at' it can no longer be downloaded; this function removes its directory and records the time. It never touches research data, and without 'dry_run = FALSE' it removes nothing. An export whose directory is absent from this private directory is reported as not present and stays recorded as not removed: its files may lie in another installation's export directory that uses the same database. With 'record_missing = TRUE' the operator confirms that they are gone, and the removal is recorded.

Usage

remove_expired_artifacts(
  repo,
  dry_run = TRUE,
  study_id = NULL,
  record_missing = FALSE
)

Arguments

Value

A table of the expired exports: identifier, profile, expiry, whether files are present and whether the removal was recorded.

Description

A worker writes an export under a temporary name, '<id>.partial', and gives it its final name only after the export is registered. A worker that was stopped while it wrote, for example by the operating system, leaves the temporary directory behind. An earlier release, which named an export before registering it, and a study export whose worker stopped just before the registration leave a complete directory under the final name, '<id>', that no registration covers. Nothing can download such directories and nothing else removes them. This function removes both kinds once they have not changed for 'older_than_hours'. Without 'dry_run = FALSE' it removes nothing. The export directory belongs to one database: a directory whose registration this database does not hold, for example after the database was restored from an older backup, is treated the same way.

Usage

remove_unfinished_exports(repo, dry_run = TRUE, older_than_hours = 1)

Arguments

Value

A table of the directories: name, hours since the last change and whether it was removed.

Description

Render a trusted packaged Quarto report without executing study text

Usage

render_study_report(data, output_dir, timeout = 60L)

Arguments

Value

Path of the rendered report.html; DEL_DEPENDENCY if Quarto is absent.

Description

A worker process that is still working on a job keeps it reserved: the reservation is extended to 'lease_seconds' from now, as long as it has not ended yet. The requester's rights are checked again when the result is recorded, with an identity that lasts as long as the reservation.

Usage

renew_job_lease(repo, job_id, lease_token, lease_seconds = 600L)

Arguments

Value

TRUE when the reservation was renewed; FALSE when it had ended or the job is no longer held by that claim. Worker infrastructure API.

Description

Verify and reproduce a portable research export without a database

Usage

reproduce_export(path)

Arguments

Value

Recomputed delphyr_analysis after all listed checksums match.

Description

Verify and reproduce a study-level research export without a database

Usage

reproduce_study_export(path)

Arguments

Value

The recomputed analysis of every round and the comparisons between rounds, after all checksums, snapshot hashes and result hashes matched.

Description

Queue a durable analysis operation

Usage

request_analysis(repo, actor, snapshot_id, command_id)

Arguments

Value

Operation id.

Description

Queue a private pseudonymized numeric research export

Usage

request_export(repo, actor, snapshot_id, command_id, purpose = NULL)

Arguments

Value

Operation id. Free-text exports require a separate reviewed profile.

Description

Profiles separate what leaves the system and who may request it: research_pseudonymized (export capability) holds every frozen round with pseudonyms, decisions, lineage and reviewed qualitative records; study_summary (analyse or manage) holds aggregates only; audit_restricted (audit or manage) holds events and approvals without response content; contacts_restricted (contacts_export) holds contact fields without pseudonyms. A public release is not produced by the software.

Usage

request_study_export(
  repo,
  actor,
  study_id,
  profile,
  command_id,
  purpose = NULL
)

Arguments

Value

Operation id and state.

Description

An uncertain delivery is never repeated automatically, because the message may already have been delivered. A coordinator decides with a rationale: 'confirmed_delivered' records that delivery was verified; 'requeue' sends it again and accepts a possible duplicate; 'abandon' stops it. Before a requeued message is sent, eligibility is checked again.

Usage

resolve_delivery(
  repo,
  actor,
  study_id,
  message_id,
  resolution,
  reason,
  command_id
)

Arguments

Value

Message UUID and its new delivery state.

Description

Revoke an unconsumed synthetic invitation

Usage

revoke_panel_invitation(
  repo,
  actor,
  study_id,
  invitation_id,
  reason,
  command_id
)

Arguments

Value

Invitation UUID.

Description

Analyse and persist a frozen snapshot

Usage

run_analysis(repo, actor, snapshot_id, command_id)

Arguments

Value

Analysis UUID and scientific result hash.

Description

Save a response with optimistic concurrency and a durable receipt

Usage

save_response(
  repo,
  actor,
  enrollment_id,
  round_item_id,
  response,
  expected_revision,
  command_id
)

Arguments

Value

Committed revision id, revision and server time.

Description

Assign or revoke a study capability

Usage

set_capability(
  repo,
  actor,
  study_id,
  principal_id,
  capability,
  enabled,
  command_id,
  reason = NULL
)

Arguments

Value

Membership id. The last management right of a study cannot be revoked: a study always keeps one person who can manage it.

Description

Change stakeholder group only for future round preparation

Usage

set_panel_group(
  repo,
  actor,
  study_id,
  panelist_id,
  group_code,
  reason,
  command_id
)

Arguments

Value

Immutable group-change receipt; existing enrollments stay unchanged.

Description

Submit the exact confirmed revision set atomically

Usage

submit_round(repo, actor, enrollment_id, expected_revision_set, command_id)

Arguments

Value

Durable submission receipt id and timestamp.

Description

Advance an authorized round through its approval lifecycle

Usage

transition_round(
  repo,
  actor,
  round_id,
  target,
  expected_hash,
  reason,
  command_id
)

Arguments

Value

Round id and new state.

Description

Validate a feedback draft and its immutable hash

Usage

validate_feedback(draft)

Arguments

Value

TRUE or DEL_VALIDATION.

Examples

validate_feedback(prepare_feedback(analyse_round(demo_snapshot())))

Description

Validate an instrument import before any database writes

Usage

validate_items(items, protocol)

Arguments

Value

TRUE or a structured validation condition.

Description

Validate a declarative study protocol

Usage

validate_protocol(protocol)

Arguments

Value

delphyr_validation with valid, issues, and schema_version.

Examples

validate_protocol(demo_protocol())

Description

Validate and normalize an answer

Usage

validate_response(value, status, scale)

Arguments

Value

List with status, value_int and value_text; DEL_VALIDATION on error.

Examples

validate_response(7, "answered", new_scale("ordinal_integer", 1:9))

Description

Stops further collection and delivery eligibility while retaining previously committed research data. This explicit synthetic policy is not a deletion workflow or a policy for use with real participants.

Usage

withdraw_participation(repo, actor, study_id, retention_policy, command_id)

Arguments

Value

Withdrawal event id and policy receipt.

Description

The requester's identity is delegated for exactly as long as this worker holds the job's reservation, as the database measures it: renewing the reservation (renew_job_lease()) extends it, and it ends when the reservation ends or another worker takes the job up. A refusal that a retry cannot change ('DEL_FORBIDDEN', 'DEL_UNAUTHORIZED', 'DEL_NOT_FOUND', 'DEL_VALIDATION') ends the job; any other failure, including a report that could not be rendered ('DEL_RENDER') and a reservation that ended before the result was recorded ('DEL_CONFLICT' with path 'job.lease'), is retried after ten seconds, up to three attempts. A rights check refused because the reservation had ended counts as such a lost reservation ('DEL_CONFLICT'), not as a refusal of the requester. An export is written under a temporary name and gets its final name only after it is registered; one that cannot be registered is removed, whatever failed.

Usage

worker_step(
  repo,
  study_id = NULL,
  lease_seconds = 600L,
  download_hours = 24,
  on_claim = NULL
)

Arguments

Value

FALSE when idle, otherwise a safe operation state.

Description

The participant-feedback profile: the released aggregate of the previous round and only this person's own previous answers.

Usage

write_participant_feedback(repo, actor, enrollment_id, output_dir)

Arguments

Value

Written file names; DEL_NOT_FOUND when no feedback is assigned.

Description

Write allowlisted numeric report supplements to a private staging directory

Usage

write_report_data(data, output_dir)

Arguments

Value

Written basenames, to include in the enclosing export manifest.