Application Structure

What an application is

An application is the plug-in unit of The Blind Machine. It defines the computation that contributors inspect before encryption, the local code that handles secret-bearing work, the server code that runs on ciphertext, the locked environment, and the tests reviewers use before trusting the bundle.

The surrounding platform stays the same across applications: registry ingest, content addressing, signing, local CLI shims, hosted sandboxing, cohort freeze, certificates, and verification.

The signed payload

Only the signed/ directory enters the application digest.

• signed/manifest.yml declares the name, version, input and output shape, release policy, resources, role mapping, and public definitions.
• signed/local_project_owner.py implements project-owner functions such as key generation, decrypt, and decode.
• signed/local_data_owner.py implements contributor functions such as input validation, encode, and encrypt.
• signed/server.py implements compute(inputs, public_context) over ciphertext only.
• signed/env/ locks the Python runtime and dependencies with pyproject.toml, uv.lock, and .python-version.

Changing any signed byte changes the application digest. Unsigned or tampered payloads are rejected before compute.

Support files

Files outside signed/ help humans review the application but do not enter the digest.

• README.md explains the scientific purpose, input format, output format, and verification expectations.
• SECURITY.md records assumptions, release risks, and application-specific caveats.
• tests/ should include vectors, expected aggregates, and local-loop equivalence checks.
• Optional benchmark notes can document payload size, runtime, and parameter tradeoffs.

Support files can change without changing the signed digest, but a serious application should keep them aligned with the signed code.

Lifecycle

1. The author writes the manifest, local roles, server role, locked environment, and tests.
2. The registry verifies the structure, computes the canonical digest over signed/, and stores a signed ApplicationVersion.
3. The project owner runs local key generation. The secret context stays local; only the public context digest is uploaded.
4. Data owners run local encode and encrypt stages. Raw inputs stay local; ciphertext contributions are uploaded.
5. The hosted worker freezes accepted ciphertext digests into a cohort commitment, verifies bundle metadata, builds the locked environment without data, and runs the compute stage without network access.
6. The encrypted result digest is bound into the certificate. The project owner decrypts and decodes locally, and verifiers check bindings and policy facts.

Examples

The public registry contains complete examples with signed payloads and browser-readable files:

• Allele Frequency Count
• Carrier Count
• Cohort Histogram
• Polygenic Score Aggregate
• Allele Frequency with Variance
• Genotype-Phenotype Covariance

For a machine-readable registry, use /api/v1/applications.

Authoring checklist

Before asking for review, make sure the application has:

• A manifest with explicit input and output schema.
• Local roles that keep raw data and secret keys on the user's machine.
• A server role with no secret-key parameter.
• A locked environment that can be rebuilt from signed/env/.
• Tests that compare local-loop and encrypted-loop behavior on seeded vectors.
• Documentation that states what the application computes, what it does not claim, and which release risks remain.