OpenLens Commons Infra Controls

Date: 2026-06-18

Status: counsel-facing infrastructure sketch. This is not legal advice and not an assertion that the current system is compliant.

Package Index

Docs:

• Internal strategy draft: docs/openlens-commons-strategy-draft-1.md
• Pre-counsel / partner governance brief: docs/openlens-commons-precounsel-partner-cut.md
• OpenLens exporter implementation plan: docs/openlens-exporter-implementation-plan.md
• OpenLens MCP / in-app agent tool plan: docs/openlens-mcp-agent-tool-plan.md
• Phase 2 Linear-ready exporter issue: docs/phase-2-openlens-exporter-issue.md
• Dread Forgejo production backlog: docs/dread-forgejo-production-backlog.md
• docs.bread deployment handoff: docs/docs-bread-deployment-handoff.md
• Narrated lawyer-meeting deck source: docs/openlens-commons-lawyer-meeting-deck.html

Schemas:

• Observation envelope: schemas/observation-envelope.schema.json
• Export manifest: schemas/export-manifest.schema.json
• Artifact manifest: schemas/artifact-manifest.schema.json

Examples and templates:

• Minimal observation envelope example: examples/minimal-observation-envelope.json
• Minimal export manifest example: examples/minimal-export-manifest.json
• Minimal artifact manifest example: examples/minimal-artifact-manifest.json
• Static artifact starter docs: templates/artifact-starter/README.md
• Static artifact starter HTML: templates/artifact-starter/index.html

Scripts:

• Draft JSON schema validator: scripts/validate_draft_json.py

Validation example:

uv run --with jsonschema python scripts/validate_draft_json.py --schema auto examples/*.json

Bottom Line

Layer separation is design direction, not current implementation.

The current Forgejo/OpenLens Hub smoke is proof-of-life green for collaboration: private git repositories, agent pushes, pull requests, and browser review work on a Dread-accessed forge. It does not yet demonstrate the controls required to operate the OpenLens Commons.

Required Architecture

L3 public research data must be a separately generated release artifact. It must not be a read permission, filtered view, branch, or path prefix over the L1 private contributor pool.

Recommended storage separation:

Layer	Repo/org	R2 bucket	Access posture
L1 private contributor pool	openlens-commons-l1-private	ol-commons-l1-raw	private, contract-governed
L2 gated benchmark	openlens-commons-l2-benchmark	ol-commons-l2-gated	commercial/API-gated
L3 public research	openlens-commons-l3-public	ol-commons-l3-public	lagged, aggregated, de-identified, citable
L4 standards	openlens-commons-standards	optional public assets bucket	schema, methodology, governance

Promotion shape:

L1 private observations
  -> validate provenance, consent, taxonomy, and hashes
  -> scrub free text and transform restricted fields
  -> enforce lag window
  -> aggregate and de-identify
  -> write a new L3 release artifact to separate L3 storage

OpenLens-To-Commons Export Pipe

The practical product workflow should be an exporter from the OpenLens database into Commons git/LFS repositories.

Recommended path:

OpenLens project/run rows
  -> select eligible prompts, responses, citations, attributes, and contexts
  -> attach Commons observation envelope and field taxonomy
  -> scrub free text and transform restricted fields
  -> write small sanitized artifacts directly to git
  -> write large artifacts through Forgejo LFS backed by R2
  -> commit signed export manifest with source ids, hashes, sanitizer version,
     taxonomy version, target layer, and reviewer/approver

This keeps the user workflow simple: "export this OpenLens project into a Commons working repo." The controls still live in the exporter, not in a manual spreadsheet. The exporter must fail closed for L2/L3 if provenance, contributor consent, taxonomy classification, free-text scrub evidence, lag evidence, or release hashes are missing.

Ownership Boundary

The OpenLens-side exporter should own the envelope and legal gate. Forgejo should own storage, verification, review, and artifact serving.

Reason: OpenLens has first-class access to product rows, project/org auth, source run ids, consent objects once added, and in-app eligibility decisions. If the legal gate lives only in Forgejo, it is too late and too detached from the database semantics.

Recommended split:

1. OpenLens exporter: selects project/run data, stamps the observation envelope, size-routes git versus LFS payloads, scrubs/transforms restricted fields, enforces layer eligibility, signs the manifest or commit request, and refuses unsafe export.
2. Forgejo/R2 substrate: stores separate L1/L2/L3 repos and buckets, records signed commits/tags/releases, runs CI verification that the manifest is present and valid, hosts pull-request review, and serves approved artifacts.
3. Analysis/artifact repos: consume exported manifests as their data contract. Python, parsers, scorers, custom tables, and HTML artifacts can be arbitrary, but they read from a signed release manifest instead of raw DB rows.

This supports the product workflow Aman described: export an OpenLens project into a working repo, let analysis code operate there, and publish polished customer artifact pages from approved manifests. Artifact generation should be downstream of a signed export so hosted pages and custom analysis code do not become side doors around Commons controls.

Required Controls Before L1 Launch

1. Storage-tier separation: L1 raw observations, L2 gated artifacts, and L3 public releases live in separate repos/orgs and separate R2 buckets.
2. No public view over raw storage: L3 is a newly written artifact from a sanitization, aggregation, de-identification, and lag pipeline.
3. Executable field taxonomy: each field is classified as allowed, restricted, sensitive, or prohibited, with allowed target layers and required transforms.
4. Observation provenance: each observation records collection method, method detail, source platform, capture time, contributor id, contributor contract id, consent scope, allowed layers, taxonomy version, and hashes.
5. Free-text scrubber: promotion runs content scrubbing over free-text fields, especially platform_responses.raw_response, brand_mentions.context, and attributes.context.
6. Fail-closed promotion: L2/L3 promotion fails if provenance, consent, taxonomy version, field transform, parent hash, derived hash, or lag-window evidence is missing.
7. Release audit trail: each promoted artifact records source hashes, transform version, sanitizer version, reviewer/approver, release timestamp, target layer, and residual restrictions.

For free-text fields, sanitization_status means a completed scrub or transform with evidence. It is not a boolean allow-list value.

Minimum Observation Envelope

The schema-valid minimal example lives at examples/minimal-observation-envelope.json.

The key requirements are:

• collection method, source platform, capture time, taxonomy version, field classifications, and content hashes are required;
• each field declares allowed layers and a public transform;
• content hashes use full sha256:<64 hex> values;
• free-text fields need sanitizer evidence before gated/public promotion.

Residual Risk

Until these controls exist:

• raw/private and public/research materials can be confused at the storage layer;
• consent and collection method can be inferred from pipeline path rather than recorded as durable observation facts;
• free-text model outputs can contain re-identifying, platform-sensitive, copyrighted, customer, or third-party material that a field allow-list alone would not catch;
• public releases can become hard to audit without parent hashes, transform versions, and approval evidence.

Required Remediation

1. Approve a field-level Commons taxonomy table with counsel.
2. Add the Commons observation envelope before Commons-bound data is collected.
3. Create separate L1/L2/L3 repos and R2 buckets with access scoped by layer.
4. Implement a one-way release pipeline from L1/L2 inputs to L3 artifacts.
5. Add a free-text sanitizer for response/context fields and store sanitizer evidence with each derived artifact.
6. Add fail-closed checks for missing provenance, consent, taxonomy, transforms, lag evidence, and release hashes.
7. Treat the current Forgejo smoke as proof-of-life, not Commons compliance evidence.

OpenLens Product Schema Reality Check

The current OpenLens product schema has useful execution lineage: prompt_runs, prompt_run_tasks, prompt_run_task_attempts, platform_responses, and derived brand mention, citation, and attribute tables.

That is enough for product observability. It is not enough for Commons governance. The current schema does not explicitly record Commons collection method, contributor contract, consent scope, allowed layer, taxonomy version, per-field classification, sanitization status, or parent/derived release hashes.

Therefore the Commons requires a net-new observation envelope and promotion pipeline rather than a small naming change around existing OpenLens rows.