Skip to content
Merged
Show file tree
Hide file tree
Changes from 4 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
18 changes: 13 additions & 5 deletions docs/content-sync.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,8 +95,11 @@ materialized or inspected for cleanliness by this operation:
Installation (below) is a different operation with its own rules: since decision F33
(1.1 point 4) it materializes absent Production Space repositories, and since the F9
addendum of 2026-10-04 it materializes the Personalspace on the two kinds of
Environment that hold one. Neither is ever fetched, fast-forwarded or prepared by it,
and repository databases and worktrees stay outside it too.
Environment that hold one. Neither is ever fetched, fast-forwarded or prepared by it.
Since the B7 amendment of 2026-10-17 it also materializes the declared data mount
(`repository_db_mount`) of a module that is there after the same install, on its
declared branch, and never fetches or changes one that exists; worktrees stay outside
it.

## Identity and rights

Expand Down Expand Up @@ -210,9 +213,14 @@ Steps, in this fixed order: `access`, `root`, `modules`, `preparation`, `check`.
3. **modules** — the children are re-read from the root as it now is: the workspace
modules, the root-level applications (`mission-control`, `design-system`) and the
Production Space repositories (decision F33, 1.1 point 4), each with a GitHub
remote in its slot. `infra` and repository databases (`mission-control/db`,
`workspace/<module>/db`) are the Organization's own bootstrap (B7) and are left out
(`excluded`). The role scope comes first: a restricted (Admin-only,
remote in its slot. A declared data mount (`materialization:
"repository_db_mount"` at `mission-control/db` or `workspace/<module>/db`) follows
its module (B7, amended 2026-10-17): materialized on its declared `git.branch`
(often `v3`) by the same function as the modules when the module is materialized or
present in this install, `excluded` when it is not; an empty directory at its place
counts as absent. A present checkout is reported as for any child (`present`, or
`blocked` for another repository) and never changed. `infra` and a database slot
declared otherwise are left out (`excluded`). The role scope comes first: a restricted (Admin-only,
`default_access` `restricted` or `private`) slot and every slot below it are in
scope only for a verified Admin; for a Steward, Builder or Reader they are
`excluded_by_role_scope` without any provider operation. A slot whose access
Expand Down
2 changes: 1 addition & 1 deletion docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -566,7 +566,7 @@ included. `docs/organization-contract.md` now says "never trusted by name" inste
| The root only from an explicit name (no discovery) | The Launchpad could not install an Organization the Folder does not hold; superseded on 2026-10-05 by name candidate and scan, each verified |
| Trust `<login>/<login>_GEN3` as the root by its name, as the resident does | A repository of that name that is not the root (a fork, a rename, a placeholder) would be installed as one; the name is only a candidate |
| Fail the run when a module's preparation is refused | The content is in place and a start prepares again (F34); reported in the step instead |
| Materialize `infra` and repository databases with the modules | F33 leaves them out of the composition; databases are the Organization's own bootstrap (B7) |
| Materialize `infra` and repository databases with the modules | F33 leaves them out of the composition; databases were the Organization's own bootstrap (B7). Superseded for declared data mounts by the B7 amendment of 2026-10-17: a module's `repository_db_mount` is materialized with its module, on its declared branch |
| Hold the Folder operation lock for the whole install | Every Folder read (status, preset) would wait behind a clone; a separate content lock instead |
| No role: GitHub denies what the account cannot read anyway | An Admin-only slot readable by a Builder (a public or wider-granted repository) would land on a Builder's Environment; the role scope decides before any provider operation, as in the resident |
| The resident's per-slot WRITE readiness gate for Builder and Steward | One unwritable module would block the whole install; the role is confirmed on the root and children are reported one by one (F9) |
Expand Down
19 changes: 19 additions & 0 deletions docs/launchpad-parity.md
Original file line number Diff line number Diff line change
Expand Up @@ -420,6 +420,25 @@ only with `--slot <name>`. Repository-db mounts stay the Organization's own boot
0188): the role is back, confirmed live on GitHub; restricted slots are in scope only
for a verified Admin and `excluded_by_role_scope` for a Steward or Builder
(`docs/content-sync.md`, Installation).*
*Amended for repository-db mounts by the Owner's direction of 2026-10-17 (DEV-6641):
a module provides its own declared data mount. A slot with `materialization:
"repository_db_mount"` directly below a module (`workspace/<module>/db`,
`mission-control/db`) is required for that module, and its preparation provides it
before every start, `lazurio module prepare` and the Launchpad's Open: an absent mount,
or an empty directory at its place, is cloned on its declared `git.branch` (often `v3`) with this Environment's GitHub
sign-in, through the same verified temporary sibling and no-replace publish as
installation (`src/content/provide.ts`, under the Folder's content lock). A checkout
already at the place is used as it is, whatever its origin or branch: never fetched,
pulled, reset or rewritten, and never a reason to refuse the start. Only providing an
absent mount can fail, and that refuses the start with the slot: `data-mount-denied`
(ask the Admin for access), `data-mount-occupied` (a non-empty directory that is no
checkout, a file or a link at the place, left untouched), `data-mount-unavailable` (GitHub or the content lock did not answer;
retried at the next start), `data-mount-clone-failed` (an empty remote, a missing
branch or an unreachable one; never bootstrapped). Installation materializes the same
mount, by the same function, when its module is materialized or present in the same
install, and leaves it `excluded` otherwise. It is still never a background sync and
never an update of an existing mount; creating a data repository stays with
`lazurio module create --data` and repository-db itself.*
Surface: "Synchronize" as the page action in the Organization view header, "Add
Organization" at the bottom of the sidebar (T3's "Add project"). No state. On a Team
Environment the identity is the broker's `gh` wrapper that Machines installs
Expand Down
7 changes: 4 additions & 3 deletions docs/workspace-composition.md
Original file line number Diff line number Diff line change
Expand Up @@ -268,9 +268,10 @@ and the declared Production Space slots (`productionspace/<repository>`), whose
repository the Environment's **composition subject** can read. Production Space
repositories are materialized and kept current like modules but never run or released;
the Launchpad shows them read-only. Repository-database mounts (`mission-control/db`,
`workspace/<module>/db`) stay the Organization's own bootstrap
([B7](launchpad-parity.md#b7-organizations-synchronize-and-materialize)) and are not
part of the composition. The subject is a
`workspace/<module>/db`) are not part of the composition: each follows its module, which
provides it at its own preparation and fresh install
([B7](launchpad-parity.md#b7-organizations-synchronize-and-materialize), amended
2026-10-17). The subject is a
GitHub principal: a user (the Operator, the person at their workstation, a persona) or
a GitHub Team (a Team Environment). Teams are not shown in the workspace; they only
decide, inside GitHub, what the subject can read. Settings → Environment keeps showing
Expand Down
15 changes: 14 additions & 1 deletion src/content/git.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,9 @@ import { repositoryPattern } from "./model";
export type CloneRequest = Readonly<{
url: string;
directory: string;
branch: "main";
/** The branch to check out: `main`, or a repository database's declared
* branch (`isBranchName`). */
branch: string;
/** Git's `credential.helper` for github.com over HTTPS: gh's; or `""` for
* an anonymous clone (a public Environment's read, `anonymousGitHub`),
* which runs isolated from every configuration, credential and helper of
Expand Down Expand Up @@ -92,6 +94,16 @@ export type GitEnvironment = Readonly<{
anonymousOrigin?: string | undefined;
}>;

/** A branch name a clone may be asked for: a declared branch such as `main`
* or `v3`, never an option, a range or a path that climbs. */
export const isBranchName = (branch: string) =>
/^[A-Za-z0-9_][A-Za-z0-9._/-]{0,99}$/.test(branch) &&
!branch.includes("..") &&
!branch.includes("//") &&
!branch.endsWith("/") &&
!branch.endsWith(".") &&
!branch.endsWith(".lock");

/** The repository of exactly `https://github.com/<owner>/<repository>.git`,
* the one URL an anonymous clone may have, or null for anything else (another
* scheme or host, credentials, a query, a fragment, a missing `.git`). */
Expand Down Expand Up @@ -293,6 +305,7 @@ export function processContentGit(environment: GitEnvironment): ContentGit {
};
return Object.freeze({
async clone(request) {
if (!isBranchName(request.branch)) return "failed";
const executable = await git();
if (executable !== undefined && request.credentialHelper === "")
return anonymousClone(executable, request);
Expand Down
99 changes: 47 additions & 52 deletions src/content/install.ts
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ import {
personalspaceOwnerOf,
templateOwnerPlaceholder,
} from "./personalspace-bootstrap";
import { dataMountOf, provideRepository } from "./provide";
import {
classifySlotAccess,
type OrganizationRole,
Expand Down Expand Up @@ -456,6 +457,10 @@ type Child = Readonly<{
excluded?: "excluded" | "excluded_by_role_scope";
/** A slot (or one above it) whose access declaration is malformed. */
unclassified?: true;
/** A repository database mount (`repository_db_mount`): cloned on its
* declared branch, and only when its module (`parent`) is materialized or
* present in the same install. */
data?: Readonly<{ parent: string; branch: string }>;
}>;

const record = (value: unknown): Readonly<Record<string, unknown>> =>
Expand All @@ -465,10 +470,12 @@ const record = (value: unknown): Readonly<Record<string, unknown>> =>

// The declared children content installation materializes (decision F33,
// 1.1 point 4): workspace modules, the root-level applications
// (`mission-control`, `design-system`) and the Production Space
// repositories. `infra` and repository databases (`mission-control/db`,
// `workspace/<module>/db`) are the Organization's own bootstrap (B7) and are
// left out. The role scope comes first, as the resident applies it
// (`mission-control`, `design-system`), the Production Space repositories
// and the declared data mount of a module (`materialization:
// "repository_db_mount"` at `mission-control/db` or `workspace/<module>/db`,
// launchpad-parity B7), on its declared branch and only below a module that
// is there after the same install. `infra` and a database slot declared
// otherwise are left out. The role scope comes first, as the resident applies it
// (`R:lazurio/runtime/lazurio-update-lib.mjs`, restricted slot policy): a
// restricted (Admin-only) slot and every slot below one are in scope only for
// a verified Admin, and are otherwise `excluded_by_role_scope`; a slot whose
Expand Down Expand Up @@ -519,6 +526,15 @@ function declaredChildren(
const kind =
slot.scope === "productionspace" ? "productionspace" : "module";
const access = boundary(slot.path);
const mount = dataMountOf(declaration);
// Only the data mount of a module: a workspace module or a root-level
// application directly above it.
const data =
mount !== null &&
(rootApplicationPaths.has(mount.parent) ||
/^workspace\/[^/]+$/.test(mount.parent))
? Object.freeze({ parent: mount.parent, branch: mount.branch })
: undefined;
children.push(
Object.freeze({
path: slot.path,
Expand All @@ -529,9 +545,10 @@ function declaredChildren(
? { unclassified: true as const }
: access === "restricted" && restricted === "exclude"
? { excluded: "excluded_by_role_scope" as const }
: !module && kind !== "productionspace"
: !module && kind !== "productionspace" && data === undefined
? { excluded: "excluded" as const }
: {}),
...(data === undefined ? {} : { data }),
}),
);
}
Expand All @@ -547,6 +564,8 @@ async function materializeChild(
root: string,
child: Child,
context: RunContext,
/** The slots this install found present or materialized so far. */
available: ReadonlySet<string>,
): Promise<RepositoryOutcome> {
const where = {
path: child.path,
Expand All @@ -559,55 +578,21 @@ async function materializeChild(
reason: "access-classification-unknown",
};
if (child.excluded !== undefined) return { ...where, result: child.excluded };
// A data mount whose module is not here: its module provides it at its
// own preparation once it is (launchpad-parity B7).
if (child.data !== undefined && !available.has(child.data.parent))
return { ...where, result: "excluded" };
if (child.repository === null) return { ...where, result: "no-repository" };
const parentSegments = child.segments.slice(0, -1);
const name = child.segments.at(-1) as string;
const destination = join(root, ...child.segments);
// A present destination is reported, never entered or changed.
const observed = await context.host.git.inspect(destination);
if (observed.kind === "checkout")
return sameRepository(observed.repository, child.repository)
? { ...where, result: "present" }
: { ...where, result: "blocked", reason: "destination-occupied" };
// GitHub's spelling of it, as this identity reads it. A public Environment
// asks GitHub nothing first: anonymous Git reads a public repository, and
// the clone of one it cannot read fails and is reported (`clone-failed`).
let fullName = child.repository;
if (!context.anonymous) {
const [owner, repositoryName] = child.repository.split("/") as [
string,
string,
];
const access = await context.host.github.repository(owner, repositoryName);
if (
access.kind === "missing" ||
(access.kind === "observed" && !access.repository.readable)
)
return { ...where, result: "denied", reason: "repository-denied" };
if (access.kind !== "observed")
return { ...where, result: "unavailable", reason: "github-unavailable" };
fullName = access.repository.fullName;
}
let parent: string;
try {
parent = await ensureCheckoutDirectories(root, parentSegments);
} catch {
return { ...where, result: "blocked", reason: "destination-invalid" };
}
const remote = await remoteOf(context, fullName);
const result = await materializeRepository({
parent,
name,
const outcome = await provideRepository({
root,
path: child.path,
repository: child.repository,
url: remote.url,
credentialHelper: remote.credentialHelper,
branch: child.data?.branch,
fillEmptyDirectory: child.data !== undefined,
git: context.host.git,
github: context.anonymous ? "anonymous" : context.host.github,
});
if (result.kind === "materialized")
return { ...where, result: "materialized" };
if (result.kind === "occupied")
return { ...where, result: "blocked", reason: "destination-occupied" };
return { ...where, result: "failed", reason: result.code };
return { ...where, ...outcome };
}

function childrenSummary(outcomes: readonly RepositoryOutcome[]): string {
Expand Down Expand Up @@ -890,8 +875,18 @@ async function installOrganization(
};
}
const repositories: RepositoryOutcome[] = [];
for (const child of declaredChildren(inventory, role.restricted))
repositories.push(await materializeChild(directory, child, context));
const available = new Set<string>();
for (const child of declaredChildren(inventory, role.restricted)) {
const outcome = await materializeChild(
directory,
child,
context,
available,
);
if (outcome.result === "materialized" || outcome.result === "present")
available.add(child.path);
repositories.push(outcome);
}
steps.done("modules", childrenSummary(repositories));
// preparation: the modules this run materialized, by the module core
steps.running("preparation");
Expand Down
13 changes: 9 additions & 4 deletions src/content/materialize.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,9 @@ import { sameRepository } from "./model";

// Materialization of one ABSENT repository (docs/content-sync.md): clone into
// a temporary sibling of the destination on the same filesystem, verify the
// clone (remote identity, branch `main`, the inspected commit and, for an
// Organization root, its declaration), then publish it with a no-replace
// clone (remote identity, its branch, `main` unless a repository database
// declares another, the inspected commit and, for an Organization root, its
// declaration), then publish it with a no-replace
// rename. An occupied destination is never touched. An interrupted run leaves
// only its own temporary sibling, recognized by its exact name and marker and
// removed only by this operation, under the content lock, the next time it
Expand Down Expand Up @@ -94,6 +95,9 @@ export type MaterializeRequest = Readonly<{
repository: string;
url: string;
credentialHelper?: string | undefined;
/** The branch cloned and verified: a repository database's declared one
* (often `v3`). Absent: `main`. */
branch?: string | undefined;
git: ContentGit;
/** More verification of the clone before it is published (the
* declaration of an Organization root): a failure code, or null. */
Expand Down Expand Up @@ -213,17 +217,18 @@ export async function materializeRepository(
parent: request.parent,
name: request.name,
fill: async (checkout): Promise<FillOutcome<string>> => {
const branch = request.branch ?? "main";
const cloned = await request.git.clone({
url: request.url,
directory: checkout,
branch: "main",
branch,
credentialHelper: request.credentialHelper,
});
if (cloned !== "cloned") return { kind: "failed", code: "clone-failed" };
const observed = await request.git.inspect(checkout);
if (
observed.kind !== "checkout" ||
observed.branch !== "main" ||
observed.branch !== branch ||
!sameRepository(observed.repository, request.repository)
)
return { kind: "failed", code: "checkout-unexpected" };
Expand Down
Loading
Loading