Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 8 additions & 12 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,13 @@

## Product boundary

This private Bun workspace contains two deliberately separate Next.js
applications, one retained editorial source library, and four shared packages:
This public Bun workspace contains one Next.js application and four internal
packages:

- `apps/problems`: the unified Vela product application at canonical
`problems.science`,
combining exact scientific State, non-authoritative Work, and advanced record
inspection;
- `apps/www`: the static Vela application at canonical `vela.space`, owning the
front page, which is its only route;
- `packages/brand`: framework-neutral tokens, fonts, marks, and licenses;
- `packages/ui`: shared React UI source built from shadcn `base-nova` on Base
UI, plus stable Vela presentation semantics;
Expand All @@ -31,9 +29,9 @@ accounts remain separate from Vela actor identities.

## Sources of truth

- Retained paintings: `apps/www/src/assets/paintings`, with their custody record
beside them; Problems keeps its own copy of the one plate it reuses
- Vela editorial routes and shell: `apps/www/src/app`
- Reviewed Problems-local painting: `apps/problems/src/assets/hero.webp`, with
its custody record beside it; the separate `vela.space` surface owns its own
assets
- Vela product routes and compositions: `apps/problems/src/app`,
`apps/problems/src/components`
- Brand contract: `packages/brand/vela.tokens.json` and its generated outputs
Expand Down Expand Up @@ -77,7 +75,7 @@ when their authors wrote them. Do not rewrite them to match the current system.
canvas, deep marine navigation, cobalt interaction, and semantic colors for
real state. Earned editorial and identity moments may reuse the canonical
sail, first-party watercolor, horizon, constellation, borrowed-light, and
long-handoff language on `apps/www`. Constellations must encode exact relationships;
long-handoff language on `vela.space`. Constellations must encode exact relationships;
nautical motifs must clarify orientation or handoff. Never turn product
controls into themed props or use literal galaxy wallpaper, glass, neon,
route hero slabs, card soup, or decorative charts.
Expand Down Expand Up @@ -110,10 +108,8 @@ when their authors wrote them. Do not rewrite them to match the current system.
## Editing workflow

- Use Bun only. Do not add npm, pnpm, Yarn, Turborepo, or app-local lockfiles.
- Keep `apps/www` static and read-only. It may import current committed release
facts and shared brand/UI source; it must not read request state, connect to
the projection or activity databases, host identity, or interpret protocol
records.
- Keep `vela.space` outside this workspace. Problems may link to it but must not
grow a second editorial application or duplicate its source here.
- Preserve exact-state semantics and the distinction between Verification and
acceptance.
- Preserve the canonical Vela sail unless an approved brand pass replaces it.
Expand Down
5 changes: 3 additions & 2 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,7 @@ accessible behavior. None supplies Vela's ontology or visual brand.

The registers are coordinated, not blended. `apps/problems` workspaces use Entire-like
dominant objects, GitHub-like files and diffs, and Hugging Face-like discovery.
The separate `apps/www` landing and living essay own the full editorial register.
The separate `vela.space` surface owns the full editorial register.
Problems Home, collection cover moments, meaningful empty states, graph
orientation, and profile accents may inherit restrained first-party materials.
Use the canonical sail and retained artwork; do not redraw the mark or generate
Expand Down Expand Up @@ -368,7 +368,8 @@ About, and other explicit editorial moments rather than beside the product
search. The one permitted ground is a masked geometric texture that no reader
could mistake for data: a line here encodes nothing.

The full long-form composition lives in `apps/www`, outside the Problems shell.
The full long-form composition lives at `vela.space`, outside this repository
and the Problems shell.
It preserves the historical continuous folio, margin notes, authored figures,
deep links, and time-of-day atmosphere. Product pages may reuse a painting or
quiet accent, but they do not import the essay layout.
Expand Down
6 changes: 3 additions & 3 deletions PRODUCT.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,9 +56,9 @@ restrained identity moments reused by Problems where they help orientation.
These surfaces may use the retained paintings and editorial type. They have
their own static shell and do not enter the Problems AppShell.

The front page source is `apps/www/src`, which holds its own retained paintings
and their custody record. Problems keeps its own copy of the one plate it
reuses. Neither app generates replacement art or redraws the sail.
The front page and its retained-painting custody live outside this repository.
Problems keeps its own reviewed copy of the one plate it reuses. Neither
surface generates replacement art or redraws the sail.

The editorial origin is live. Problems links to `https://vela.space`; its
`/about/endless-frontiers` address is retained only as a permanent cross-origin
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,7 +136,7 @@ Git repository preserves exact Submissions and scoped Verification evidence.
Neither production nor Verification changes Standing. Only an authorized,
attributed Decision in that named Repository changes Standing;
the performer may be human or agent, and deterministic replay
derives the successor state and current actions. Vela Web provides the
derives the successor state and current actions. Problems provides the
read-only map, contribution handoff, and review surfaces.

```text
Expand Down Expand Up @@ -190,7 +190,7 @@ npm, pnpm, Yarn, Turborepo, or per-application lockfiles.
```bash
bun install --frozen-lockfile
bun run dev:problems # http://127.0.0.1:4322
bun run dev:www # configurable local editorial preview
bun run dev:demo # deterministic local Problems data, no credentials
```

## Verify a release candidate
Expand Down
40 changes: 33 additions & 7 deletions docs/WEB.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ Earlier design and migration plans live under `docs/history/`.
readers across current
change, direct contribution, communities, and the exact scientific record. Advanced
records remain available in the same runtime.
- `vela.space` is the separate static origin compiled by `apps/www` from its
own `src`. It publishes one page. The *Endless Frontiers* essay was published
there at `/constellations` and was removed on 2026-08-21.
- `vela.space` is a separate static origin outside this repository. It
publishes one page. The *Endless Frontiers* essay was published there at
`/constellations` and was removed on 2026-08-21.
- Hosted Vela is non-authoritative. The Problems reads a bounded SELECT-only
projection from Neon. Work mode writes hosted research activity through
`@vela/activity-data`. Canonical custody remains in Repository Git
Expand All @@ -28,12 +28,10 @@ the named identity files. The package-direction check keeps
`@vela/projection-data` independent of mutable activity and limits
`@vela/activity-data` reuse to exact canonical and read contracts.

The repository is a Bun workspace with six maintained runtime boundaries and
one non-runnable content area:
The repository is a Bun workspace with five maintained runtime boundaries:

```text
apps/problems Vela Problems product: Problem State, Work, and Records
apps/www static Vela front page, one route
packages/brand governed identity, tokens, fonts, and delivery assets
packages/ui shared shadcn/Base UI source and Vela presentation semantics
packages/projection-data Git-to-Neon projection, validation, search, and manifests
Expand Down Expand Up @@ -141,6 +139,33 @@ database in the `vela-problems-projection` Neon project:
bun run release:problems
```

The release transaction acquires every declared public source from the checked
locks, writes one content-addressed adapter artifact, and retains it as a public
release asset in `vela-science/problems`. New projection manifests use
`vela.projection-source-adapter-artifact-reference.v3`; its retrieval contract
is unauthenticated. Historical v2 manifests remain readable as history but are
never emitted by the current builder.

A clean public checkout can prepare the same input class without access to
`vela-web`:

```bash
bun run sources:refresh -- \
--output /tmp/vela-source-adapters \
--artifact-directory /tmp

bun run projection:reconstruct -- \
--repositories-root /path/containing/public-math-checkout \
--vela /path/to/the-digest-verified-released-vela-0.977.6-binary \
--source-adapter-artifact /tmp/vela-projection-source-adapters-<root>.json \
--production-parity skip \
--output /tmp/vela-problems-clean-room.json
```

The skip is only for a noncanonical preactivation candidate. C1 qualification
must use the default required production comparison against the SELECT-only
reader; activation remains a separate operator-controlled stage.

Refresh refuses dirty or unpushed sources, wrong branches or remotes, Vela
version or released-binary-byte drift, packet drift, missing decision evidence,
incomplete reviews, root disagreement, and every ambient corpus-drop override.
Expand Down Expand Up @@ -174,7 +199,8 @@ table roots, and source roots are identical. After activation, the same operator
transaction stages any editorial snapshot, requalifies and reconstructs the
clean local commit, publishes that exact commit, deploys it through Vercel's
exact Git-SHA API, verifies production, and retains a qualification record.
The content-addressed source-adapter artifact is retained before activation.
The content-addressed source-adapter artifact is retained as an unauthenticated
public release asset in `vela-science/problems` before activation.
An exact remote lock prevents two operators from interleaving those stages.

Run this transaction immediately after an accepted canonical Math change and
Expand Down
4 changes: 2 additions & 2 deletions docs/design-system.md
Original file line number Diff line number Diff line change
Expand Up @@ -256,8 +256,8 @@ publication compositions stay app-local CSS modules. Shared controls, focus,
tokens, motion limits, and type sources still come from `@vela/ui` and
`@vela/brand`.

The front page source is `apps/www/src`, with painting provenance beside the
plates. The essay it once carried was removed on 2026-08-21.
The front page source and its painting provenance live outside this repository.
The essay it once carried was removed on 2026-08-21.
Problems selectively consumes reviewed paintings and current passages in its
brand register; the source does not become a second design system or runtime.

Expand Down
4 changes: 2 additions & 2 deletions docs/projection-provenance.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Problems product provenance

`apps/problems` is a new implementation in the consolidated `vela-web`
history. The archived `vela-site` repository was studied at commit
`apps/problems` is the canonical implementation extracted from the historical
private `vela-web` line. The archived `vela-site` repository was studied at commit
`34e3f20` for product anatomy: its inset shell, collapsible navigation,
contextual header, dense ledgers, metadata rail, command palette, and stable
deep-link behavior.
Expand Down
2 changes: 1 addition & 1 deletion docs/security/vela-web-threat-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -257,7 +257,7 @@ flowchart LR
| Public State routes | Anonymous HTTP GET | Internet -> exact reader | SELECT-only scientific projection | `apps/problems/src/app/p/[repository]/[problem]/page.tsx`; `AGENTS.md` |
| AuthKit proxy and `currentAccount` | Browser session | Internet -> WorkOS -> app | Hosted identity only; validates redirect and cookie configuration | `apps/problems/src/proxy.ts`; `apps/problems/src/lib/auth.ts` |
| GitHub connection adapter | WorkOS GitHub identity, signed App installation, selected repository metadata | Internet -> GitHub -> app -> Activity | HMAC-bound setup state; Octokit webhook verification; delivery-root deduplication; short-lived read-only installation tokens; no source-byte or token persistence | `apps/problems/src/lib/github-app.ts`; `apps/problems/src/app/api/github`; `packages/activity-data/schema/github-codebases.sql` |
| Core integration inspector | Temporary exact GitHub archive at an immutable commit | app -> pinned Vela 0.977.3 CLI | Bounded link-free extraction; closed authority-neutral JSON; temporary bytes removed after inspection | `apps/problems/src/lib/codebase-inspection.ts`; `packages/projection-data/src/core-integration.ts` |
| Core integration inspector | Temporary exact GitHub archive at an immutable commit | app -> pinned released Vela 0.977.6 CLI | Bounded link-free extraction; closed authority-neutral JSON; temporary bytes removed after inspection | `apps/problems/src/lib/codebase-inspection.ts`; `packages/projection-data/src/core-integration.ts` |
| Workspace Server Actions | Authenticated form submit | Browser -> server | One declared action file; recomputes exact anchor | `apps/problems/src/app/actions/activity.ts` |
| Draft export | Authenticated GET | Browser -> server -> activity API | Membership-required canonical bytes; private/no-store | `apps/problems/src/app/drafts/[id]/export/route.ts`; `activity_api.export_submission_draft` |
| Activity SQL API | Parameterized SQL | server -> separate database | `SECURITY DEFINER`, fixed search path, membership and command allowlist | `packages/activity-data/src/activity.ts`; `packages/activity-data/migrations/20260811_activity_v1.sql` |
Expand Down
6 changes: 3 additions & 3 deletions packages/activity-data/config/vela-schemas.v1.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
{
"schema": "site.vela-schemas.v1",
"vela_version": "0.977.3",
"vela_tag": "v0.977.3",
"vela_commit": "1c1abe8f365f16803fea889bf9280877992a6d02",
"vela_version": "0.977.6",
"vela_tag": "v0.977.6",
"vela_commit": "9ac8e7730bfb63a3b8eb1d2e1d91081c3e703c59",
"files": [
{
"file": "submission.schema.json",
Expand Down
6 changes: 3 additions & 3 deletions packages/activity-data/tests/draft-submission.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,9 @@ describe("vela.submission.v3 drafts", () => {
.toBe("sha256:c931f3a454c2a6544ac08e40adb2e0eb77f71131b7593957de8ff88f748d7318");
expect(provenance.files[0].sha256).toBe(schemaRoot);
expect(provenance).toMatchObject({
vela_version: "0.977.3",
vela_tag: "v0.977.3",
vela_commit: "1c1abe8f365f16803fea889bf9280877992a6d02",
vela_version: "0.977.6",
vela_tag: "v0.977.6",
vela_commit: "9ac8e7730bfb63a3b8eb1d2e1d91081c3e703c59",
});
const exported = createSubmissionDraftExport(fixture());
expect(exported.payload.schema).toBe("vela.submission.v3");
Expand Down
18 changes: 9 additions & 9 deletions packages/projection-data/config/vela-release.v1.json
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
{
"schema": "vela.release-record.v1",
"version": "0.977.3",
"tag": "v0.977.3",
"commit": "1c1abe8f365f16803fea889bf9280877992a6d02",
"release_url": "https://github.com/vela-science/vela/releases/tag/v0.977.3",
"docs_url": "https://github.com/vela-science/vela/blob/1c1abe8f365f16803fea889bf9280877992a6d02/docs",
"generator_binary_sha256": "sha256:89e5f366db5480a011c722bdc7d3c7f09e07fe78c0cd2855d2e53d3a419520a0",
"macos_generator_binary_sha256": "sha256:3a1173918bdcb887155bab681411bf5e9ff64d925fe1b50369ac37ab020b94ad",
"linux_archive_sha256": "sha256:072af0182152ac4b4a8f04cec7e37f1dc3b5b7a42f49ef4066cce559e26835b3",
"macos_archive_sha256": "sha256:f1299f217985c1eecdfb20ef8750014bbf7b2fc6d3cc31ca33bdd433e2be8991"
"version": "0.977.6",
"tag": "v0.977.6",
"commit": "9ac8e7730bfb63a3b8eb1d2e1d91081c3e703c59",
"release_url": "https://github.com/vela-science/vela/releases/tag/v0.977.6",
"docs_url": "https://github.com/vela-science/vela/blob/9ac8e7730bfb63a3b8eb1d2e1d91081c3e703c59/docs",
"generator_binary_sha256": "sha256:e476ece52cb5f356519f890533f06c918fb10f3dd00268092d490701f7fd1b65",
"macos_generator_binary_sha256": "sha256:5b21415c98503b20518c0e68714b0b4f4b3c371525ea110563b89a53a0d3dbb3",
"linux_archive_sha256": "sha256:a8cb120a01211fbb40b5da6d697b0fc8e4a84b0d76e62cfa574a2518bdebb83e",
"macos_archive_sha256": "sha256:62ea9006e086b40f0431b2ce2cf74827518f37dc58e329353920083f50dad874"
}
6 changes: 3 additions & 3 deletions packages/projection-data/config/vela-schemas.v1.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
{
"schema": "site.vela-schemas.v1",
"vela_version": "0.977.3",
"vela_tag": "v0.977.3",
"vela_commit": "1c1abe8f365f16803fea889bf9280877992a6d02",
"vela_version": "0.977.6",
"vela_tag": "v0.977.6",
"vela_commit": "9ac8e7730bfb63a3b8eb1d2e1d91081c3e703c59",
"files": [
{
"file": "vela-status-v4.schema.json",
Expand Down
60 changes: 39 additions & 21 deletions packages/projection-data/scripts/reconstruct-projection.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,7 @@ export function parseArgs(argv) {
"repositories-root",
"vela",
"source-adapter-artifact",
"production-parity",
"output",
]);
const values = new Map();
Expand All @@ -165,6 +166,11 @@ export function parseArgs(argv) {
values.set(name, value);
}
const vela = values.get("vela") ?? process.env.VELA_BIN ?? "vela";
const productionParity = values.get("production-parity") ?? "required";
invariant(
productionParity === "required" || productionParity === "skip",
"--production-parity must be required or skip",
);
return {
repositoriesRoot: resolve(values.get("repositories-root") ?? join(repositoryRoot, "..")),
vela: vela.includes("/") ? resolve(vela) : vela,
Expand All @@ -173,6 +179,7 @@ export function parseArgs(argv) {
?? process.env.VELA_SOURCE_ADAPTER_ARTIFACT
?? "",
),
productionParity,
output: values.has("output") ? resolve(values.get("output")) : null,
};
}
Expand Down Expand Up @@ -520,22 +527,38 @@ export async function reconstructProjection(options) {
invariant(canonicalJson(runs[0]) === canonicalJson({ ...runs[1], attempt: 1 }), "two database reconstructions disagree");
reportPhase("database_comparison_complete");

const activeDatabaseUrl = process.env.VELA_PROJECTION_DATABASE_URL;
invariant(activeDatabaseUrl, "VELA_PROJECTION_DATABASE_URL is required for active projection parity");
const active = new SQL(activeDatabaseUrl, { max: 1, prepare: false });
let production;
try {
production = await currentStoredRelease(active);
} finally {
await active.close();
let productionParity;
if (options.productionParity === "skip") {
productionParity = {
status: "skipped",
source: null,
release_root: null,
reason: "explicit noncanonical preactivation qualification",
};
} else {
const activeDatabaseUrl = process.env.VELA_PROJECTION_DATABASE_URL;
invariant(activeDatabaseUrl, "VELA_PROJECTION_DATABASE_URL is required for active projection parity");
const active = new SQL(activeDatabaseUrl, { max: 1, prepare: false });
let production;
try {
production = await currentStoredRelease(active);
} finally {
await active.close();
}
invariant(production, "active projection database has no current release");
const parity = compareProductionProjection(candidates[0].manifest, production);
invariant(parity.manifest_schema_equal, "active projection manifest schema drift");
invariant(parity.vela_version_equal, "active projection Vela version drift");
invariant(parity.table_roots_equal, "active projection table-root drift");
invariant(parity.source_repositories_equal, "active projection Repository input drift");
invariant(parity.source_registry_equal, "active projection source-registry drift");
productionParity = {
status: "pass",
source: "active_projection_database",
release_root: production.release_root,
...parity,
};
}
invariant(production, "active projection database has no current release");
const parity = compareProductionProjection(candidates[0].manifest, production);
invariant(parity.manifest_schema_equal, "active projection manifest schema drift");
invariant(parity.vela_version_equal, "active projection Vela version drift");
invariant(parity.table_roots_equal, "active projection table-root drift");
invariant(parity.source_repositories_equal, "active projection Repository input drift");
invariant(parity.source_registry_equal, "active projection source-registry drift");

const body = {
schema: "vela.projection-clean-room-qualification.v1",
Expand All @@ -561,12 +584,7 @@ export async function reconstructProjection(options) {
byte_identical: true,
reader_select_only: true,
},
production_parity: {
status: "pass",
source: "active_projection_database",
release_root: production.release_root,
...parity,
},
production_parity: productionParity,
limitations: [
"The macOS reconstruction has a distinct release root when production was generated by the recorded Linux binary; exact table roots, Repository inputs, and source-registry roots must still match.",
"The same frozen source-adapter artifact is used twice; this proves reconstruction, not future reacquisition from mutable upstream sources.",
Expand Down
Loading