@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/domain/src/versions/version-resolution.js

@@ -0,0 +1,111 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { ComponentId } from "./component-id.js";
+import { LockedComponent } from "./locked-component.js";
+import { VersionError } from "./version-error.js";
+import { VersionSelector } from "./version-selector.js";
+const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/;
+export function recordedTarget(target) {
+    return target.replace(/[?#].*$/s, "").replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/@]*@/i, "$1");
+}
+export class VersionResolution {
+    resolvedAt;
+    lockDigest;
+    entries;
+    locked;
+    writesLock = false;
+    constructor(resolvedAt, 
+    lockDigest, entries, locked) {
+        this.resolvedAt = resolvedAt;
+        this.lockDigest = lockDigest;
+        this.entries = entries;
+        this.locked = locked;
+        Object.freeze(this);
+    }
+    static create(input) {
+        if (!ISO_UTC.test(input.resolvedAt))
+            throw new VersionError("invalid", "resolvedAt must be an ISO time in UTC");
+        const entries = new Map();
+        for (const entry of input.components) {
+            const id = entry.id.toString();
+            if (entries.has(id))
+                throw new VersionError("invalid", `The resolution names ${id} twice`);
+            if (!entry.component.id.equals(entry.id))
+                throw new VersionError("invalid", `Resolved ${entry.component.id} under ${id}`);
+            if (entry.selector.kind === "locked" && entry.origin !== "lock")
+                throw new VersionError("invalid", `${id}: "locked" resolves from the lock only`);
+            if (entry.selector.kind !== "locked" && entry.origin === "lock")
+                throw new VersionError("invalid", `${id}: only "locked" resolves from the lock`);
+            entries.set(id, Object.freeze({ ...entry, fetches: Object.freeze(entry.fetches.map((fetch) => Object.freeze({ ...fetch, target: recordedTarget(fetch.target) }))) }));
+        }
+        const locked = new Map((input.lock?.components ?? []).map((component) => [component.id.toString(), component]));
+        return new VersionResolution(input.resolvedAt, input.lock?.digest, entries, locked);
+    }
+    static fromJSON(data) {
+        const value = data;
+        if (!value || value.kind !== "product-lab-version-resolution" || value.schemaVersion !== 1)
+            throw new VersionError("invalid", "Not a product-lab version resolution (kind product-lab-version-resolution, schemaVersion 1)");
+        const components = Object.entries(value.components ?? {}).map(([id, entry]) => ({
+            id: ComponentId.parse(id),
+            selector: VersionSelector.parse(entry.selector),
+            origin: entry.origin,
+            candidate: entry.candidate === true,
+            component: LockedComponent.create(id, entry.resolved),
+            fetches: entry.fetches ?? [],
+        }));
+        const digest = "digest" in (value.lock ?? {}) ? value.lock.digest : undefined;
+        return VersionResolution.create({ resolvedAt: value.resolvedAt, ...(digest ? { lock: { digest, components: [] } } : {}), components });
+    }
+    ids() {
+        return [...this.entries.keys()].sort();
+    }
+    get(id) {
+        return this.entries.get(ComponentId.parse(id).toString());
+    }
+    components() {
+        return this.ids().map((id) => this.entries.get(id));
+    }
+    unlocked() {
+        return this.components().filter((entry) => entry.origin === "source");
+    }
+    get differsFromLock() {
+        return this.unlocked().some((entry) => {
+            const locked = this.locked.get(entry.id.toString());
+            return !locked || !locked.sameArtifact(entry.component);
+        });
+    }
+    combination() {
+        return Object.fromEntries(this.components().map((entry) => [
+            entry.id.toString(),
+            {
+                version: entry.component.version,
+                digests: Object.fromEntries(Object.entries(entry.component.digests).map(([name, digest]) => [name, digest.toString()])),
+            },
+        ]));
+    }
+    toJSON() {
+        return {
+            kind: "product-lab-version-resolution",
+            schemaVersion: 1,
+            resolvedAt: this.resolvedAt,
+            lock: this.lockDigest ? { digest: this.lockDigest } : { absent: true },
+            writesLock: false,
+            components: Object.fromEntries(this.components().map((entry) => {
+                const locked = this.locked.get(entry.id.toString());
+                return [
+                    entry.id.toString(),
+                    {
+                        selector: entry.selector.toJSON(),
+                        origin: entry.origin,
+                        ...(entry.candidate ? { candidate: true } : {}),
+                        ...(entry.origin === "source" && this.lockDigest
+                            ? { lock: locked ? { version: locked.version, sameArtifact: locked.sameArtifact(entry.component) } : { absent: true } }
+                            : {}),
+                        resolved: entry.component.toJSON(),
+                        fetches: entry.fetches,
+                    },
+                ];
+            })),
+        };
+    }
+}

package/core/domain/src/versions/version-selector.d.ts

@@ -0,0 +1,58 @@
+import { ReleaseVersion } from "./release-version.js";
+/**
+ * How a selector may be written (docs/design.md, section 19): a keyword, an
+ * explicit version, a release of a named repository, or a git ref.
+ *
+ * - `"locked"`: exactly what `lab.lock.json` records.
+ * - `"deployed"`: what the live network runs now (runtimes: the code hash at a recent finalized block).
+ * - `"latest-release"`: the newest published release.
+ * - `"0.20.0"`, `"v0.0.26-paseo"`: an explicit version of the component's configured repository.
+ * - `{ release: "owner/repo@tag" }` or `"release:owner/repo@tag"`: an explicit release of a named repository.
+ * - `{ git: "owner/repo" | "<alias>", ref: "c7449d3a" }` or `"git:<repo>@<ref>"`: a commit, tag or branch.
+ */
+export type VersionSelectorInput = string | {
+    readonly release: string;
+} | {
+    readonly git: string;
+    readonly ref: string;
+};
+export type VersionSelectorKind = "locked" | "deployed" | "latest-release" | "version" | "git";
+/** Why `ref` is not a valid git ref name (a subset of `git check-ref-format`), or undefined when it is. */
+export declare function gitRefProblem(ref: string): string | undefined;
+/**
+ * A validated version selector: parse once, then ask what it means. Immutable;
+ * `toString()` is its canonical text form and `toJSON()` the form it was
+ * written in (keyword, version string, or `{ release }` / `{ git, ref }`).
+ */
+export declare class VersionSelector {
+    readonly kind: VersionSelectorKind;
+    /** `version`: the version or tag. */
+    readonly version?: string | undefined;
+    /** `version` with a named repository, and `git`: the repository (`owner/repo` or an alias). */
+    readonly repository?: string | undefined;
+    /** `git`: the ref (commit, tag or branch). */
+    readonly ref?: string | undefined;
+    private constructor();
+    static readonly LOCKED: VersionSelector;
+    static readonly DEPLOYED: VersionSelector;
+    static readonly LATEST_RELEASE: VersionSelector;
+    static parse(input: unknown): VersionSelector;
+    private static parseText;
+    /** An explicit release of a named repository, `owner/repo@tag` (the tag may itself contain `@`). */
+    static release(spec: string): VersionSelector;
+    static git(repository: string, ref: string): VersionSelector;
+    /** `git` naming a commit (7-40 lower-case hex digits) rather than a tag or branch. */
+    get isCommit(): boolean;
+    /**
+     * Whether what it names can change without anyone editing the lab:
+     * `deployed` (a runtime upgrade), `latest-release` (a publication), a git
+     * tag or branch. Explicit versions and commits do not move; `locked` moves
+     * only when someone rewrites the lock.
+     */
+    get moving(): boolean;
+    /** The explicit version as a comparable release version, when it is one. */
+    get releaseVersion(): ReleaseVersion | undefined;
+    equals(other: VersionSelector | VersionSelectorInput): boolean;
+    toString(): string;
+    toJSON(): VersionSelectorInput;
+}

package/core/domain/src/versions/version-selector.js

@@ -0,0 +1,134 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { ReleaseVersion } from "./release-version.js";
+import { VersionError } from "./version-error.js";
+const REPOSITORY = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const ALIAS = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const COMMIT = /^[0-9a-f]{7,40}$/;
+const EXPLICIT_VERSION = /^v?\d+(?:\.\d+){0,3}(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const NOT_SELECTORS = {
+    latest: `"latest" is not a selector; write "latest-release" (newest published release) or "deployed" (what the network runs)`,
+    "deployed-ios": `"deployed-ios" needs a registry of the truAPI version production phones ship, which nobody maintains yet (docs/design.md, section 19)`,
+    "deployed-android": `"deployed-android" needs a registry of the truAPI version production phones ship, which nobody maintains yet (docs/design.md, section 19)`,
+};
+export function gitRefProblem(ref) {
+    if (typeof ref !== "string" || !ref.length)
+        return "is empty";
+    if (ref.length > 255)
+        return "is longer than 255 characters";
+    if (/[\u0000- \u007f~^:?*[\\]/.test(ref))
+        return "contains a space, a control character or one of ~ ^ : ? * [ \\";
+    if (ref.includes("..") || ref.includes("@{") || ref.includes("//"))
+        return 'contains "..", "@{" or "//"';
+    if (/^[-/.]|[/.]$|\.lock$|\/\./.test(ref) || ref === "@")
+        return 'starts with "-", "/" or ".", ends with "/", "." or ".lock", or is "@"';
+    return undefined;
+}
+export class VersionSelector {
+    kind;
+    version;
+    repository;
+    ref;
+    constructor(kind, 
+    version, 
+    repository, 
+    ref) {
+        this.kind = kind;
+        this.version = version;
+        this.repository = repository;
+        this.ref = ref;
+        Object.freeze(this);
+    }
+    static LOCKED = new VersionSelector("locked");
+    static DEPLOYED = new VersionSelector("deployed");
+    static LATEST_RELEASE = new VersionSelector("latest-release");
+    static parse(input) {
+        if (input instanceof VersionSelector)
+            return input;
+        if (typeof input === "string")
+            return VersionSelector.parseText(input);
+        if (input && typeof input === "object" && !Array.isArray(input)) {
+            const record = input;
+            const keys = Object.keys(record).sort().join(",");
+            if (keys === "release" && typeof record.release === "string")
+                return VersionSelector.release(record.release);
+            if (keys === "git,ref" && typeof record.git === "string" && typeof record.ref === "string")
+                return VersionSelector.git(record.git, record.ref);
+            throw new VersionError("invalid", `A selector object is { release: "owner/repo@tag" } or { git: "<repo>", ref: "<ref>" }, not ${JSON.stringify(input)}`);
+        }
+        throw new VersionError("invalid", `A version selector is a string or { release } / { git, ref }, not ${input === null ? "null" : typeof input}`);
+    }
+    static parseText(text) {
+        const trimmed = text.trim();
+        if (trimmed !== text || !text)
+            throw new VersionError("invalid", `Version selector ${JSON.stringify(text)} is empty or has surrounding spaces`);
+        if (text === "locked")
+            return VersionSelector.LOCKED;
+        if (text === "deployed")
+            return VersionSelector.DEPLOYED;
+        if (text === "latest-release")
+            return VersionSelector.LATEST_RELEASE;
+        if (NOT_SELECTORS[text])
+            throw new VersionError("invalid", NOT_SELECTORS[text]);
+        if (text.startsWith("release:"))
+            return VersionSelector.release(text.slice("release:".length));
+        if (text.startsWith("git:")) {
+            const rest = text.slice("git:".length);
+            const at = rest.indexOf("@");
+            if (at < 0)
+                throw new VersionError("invalid", `Git selector ${JSON.stringify(text)} must be git:<repo>@<ref>`);
+            return VersionSelector.git(rest.slice(0, at), rest.slice(at + 1));
+        }
+        if (EXPLICIT_VERSION.test(text))
+            return new VersionSelector("version", text);
+        throw new VersionError("invalid", `Unknown version selector ${JSON.stringify(text)}: use locked, deployed, latest-release, an explicit version (0.20.0), release:<owner/repo>@<tag> or git:<repo>@<ref>`);
+    }
+    static release(spec) {
+        const at = spec.indexOf("@");
+        const repository = at < 0 ? "" : spec.slice(0, at);
+        const tag = at < 0 ? "" : spec.slice(at + 1);
+        if (!REPOSITORY.test(repository))
+            throw new VersionError("invalid", `Release ${JSON.stringify(spec)} must be owner/repo@tag`);
+        const problem = gitRefProblem(tag);
+        if (problem)
+            throw new VersionError("invalid", `Release tag ${JSON.stringify(tag)} ${problem}`);
+        return new VersionSelector("version", tag, repository);
+    }
+    static git(repository, ref) {
+        if (!REPOSITORY.test(repository) && !ALIAS.test(repository))
+            throw new VersionError("invalid", `Git repository ${JSON.stringify(repository)} must be owner/repo or a configured alias (lower-case)`);
+        const problem = gitRefProblem(ref);
+        if (problem)
+            throw new VersionError("invalid", `Git ref ${JSON.stringify(ref)} ${problem}`);
+        return new VersionSelector("git", undefined, repository, ref);
+    }
+    get isCommit() {
+        return this.kind === "git" && COMMIT.test(this.ref);
+    }
+    get moving() {
+        return this.kind === "deployed" || this.kind === "latest-release" || (this.kind === "git" && !this.isCommit);
+    }
+    get releaseVersion() {
+        return this.kind === "version" ? ReleaseVersion.parse(this.version) : undefined;
+    }
+    equals(other) {
+        return this.toString() === VersionSelector.parse(other).toString();
+    }
+    toString() {
+        switch (this.kind) {
+            case "version":
+                return this.repository ? `release:${this.repository}@${this.version}` : this.version;
+            case "git":
+                return `git:${this.repository}@${this.ref}`;
+            default:
+                return this.kind;
+        }
+    }
+    toJSON() {
+        if (this.kind === "git")
+            return { git: this.repository, ref: this.ref };
+        if (this.kind === "version" && this.repository)
+            return { release: `${this.repository}@${this.version}` };
+        return this.toString();
+    }
+}

package/core/domain/src/versions/version-workspace-key.d.ts

@@ -0,0 +1,18 @@
+import type { VersionCombination } from "./version-drift.js";
+import type { VersionResolution } from "./version-resolution.js";
+/**
+ * The name of the workspace that belongs to one version combination: equal
+ * combinations (same components, versions and digests) give the same key, any
+ * difference another. Switching versions therefore selects or creates another
+ * workspace instead of reusing chain data or identities made with other
+ * versions (docs/design.md, section 19). FNV-1a over the canonical
+ * combination: a name, not a security digest (the digests inside are).
+ */
+export declare class VersionWorkspaceKey {
+    readonly value: string;
+    private constructor();
+    static of(combination: VersionCombination | VersionResolution): VersionWorkspaceKey;
+    equals(other: VersionWorkspaceKey | string): boolean;
+    toString(): string;
+    toJSON(): string;
+}

package/core/domain/src/versions/version-workspace-key.js

@@ -0,0 +1,41 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+const FNV_OFFSET = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x100000001b3n;
+const MASK = 0xffffffffffffffffn;
+export class VersionWorkspaceKey {
+    value;
+    constructor(value) {
+        this.value = value;
+        Object.freeze(this);
+    }
+    static of(combination) {
+        const value = "combination" in combination ? combination.combination() : combination;
+        const canonical = Object.keys(value)
+            .sort()
+            .map((id) => {
+            const { version, digests } = value[id];
+            const named = Object.keys(digests)
+                .sort()
+                .map((name) => `${name}=${digests[name]}`)
+                .join(",");
+            return `${id}|${version}|${named}`;
+        })
+            .join("\n");
+        let hash = FNV_OFFSET;
+        for (let index = 0; index < canonical.length; index++) {
+            hash ^= BigInt(canonical.charCodeAt(index));
+            hash = (hash * FNV_PRIME) & MASK;
+        }
+        return new VersionWorkspaceKey(`versions-${hash.toString(16).padStart(16, "0")}`);
+    }
+    equals(other) {
+        return this.value === String(other);
+    }
+    toString() {
+        return this.value;
+    }
+    toJSON() {
+        return this.value;
+    }
+}

package/core/domain/src/versions/versioned-workspace.d.ts

@@ -0,0 +1,43 @@
+import { type RecoveryDecision } from "./recovery-policy.js";
+import { VersionResolution } from "./version-resolution.js";
+/** Whether an existing workspace may be resumed: the recovery policy's answer, or a refusal because versions are unknown on one side. */
+export type WorkspaceResumeDecision = RecoveryDecision | {
+    readonly action: "refuse";
+    /** `unrecorded`: the workspace records no versions; `unresolved`: it does, and the run resolved none; `misnamed`: its name belongs to other versions. */
+    readonly reason: "unrecorded" | "unresolved" | "misnamed";
+    readonly workspace: string;
+    readonly message: string;
+};
+/**
+ * Workspaces per version combination (docs/design.md, section 19: switching
+ * versions creates or selects a separate workspace and never overwrites chain
+ * data or identities made with other versions). A named workspace `manual`
+ * run with a resolution lives in `manual.versions-<key>`, the key being the
+ * combination's `VersionWorkspaceKey`: another combination selects or creates
+ * another directory. Resuming checks the combination the workspace recorded
+ * against the run's through `RecoveryPolicy`; nothing here ever resets.
+ */
+export declare class VersionedWorkspace {
+    private constructor();
+    /**
+     * The workspace name for `base` under `resolution`. A name that already
+     * carries a key (`manual.versions-…`) is an explicit selection and is kept:
+     * resuming it with other versions is refused, not redirected.
+     */
+    static select(base: string, resolution: VersionResolution): string;
+    /** The key a versioned name carries, or undefined for a plain name. */
+    static keyOf(name: string): string | undefined;
+    /**
+     * Whether the workspace `name`, which recorded `recorded` (a
+     * `VersionResolution` or its JSON) when it was created, may be resumed by a
+     * run that resolved `current`. Neither side known: resume (versions are not
+     * in play). One side unknown: refuse. Both: `RecoveryPolicy`.
+     */
+    static resume(input: {
+        name: string;
+        recorded?: unknown;
+        current?: VersionResolution;
+    }): WorkspaceResumeDecision;
+    /** The name without its version key. */
+    static baseOf(name: string): string;
+}

package/core/domain/src/versions/versioned-workspace.js

@@ -0,0 +1,63 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { RecoveryPolicy } from "./recovery-policy.js";
+import { VersionError } from "./version-error.js";
+import { VersionResolution } from "./version-resolution.js";
+import { VersionWorkspaceKey } from "./version-workspace-key.js";
+const BASE = /^[A-Za-z0-9_][\w.-]{0,37}$/;
+const VERSIONED = /^(.+)\.(versions-[0-9a-f]{16})$/;
+export class VersionedWorkspace {
+    constructor() { }
+    static select(base, resolution) {
+        if (VERSIONED.test(base))
+            return base;
+        if (!BASE.test(base) || base === "." || base === "..")
+            throw new VersionError("invalid", `Workspace name ${JSON.stringify(base)} must be 1-38 letters, digits, ".", "_" or "-" to carry a version key`);
+        return `${base}.${VersionWorkspaceKey.of(resolution).value}`;
+    }
+    static keyOf(name) {
+        return VERSIONED.exec(name)?.[2];
+    }
+    static resume(input) {
+        const { name, current } = input;
+        if (input.recorded === undefined && current === undefined)
+            return { action: "resume", workspace: name };
+        if (input.recorded === undefined)
+            return {
+                action: "refuse",
+                reason: "unrecorded",
+                workspace: name,
+                message: `Workspace ${name} records no versions, so it cannot be confirmed to match ${VersionWorkspaceKey.of(current).value}. Recovery never guesses: select the workspace for these versions (${VersionedWorkspace.select(VersionedWorkspace.baseOf(name), current)}).`,
+            };
+        const recorded = input.recorded instanceof VersionResolution ? input.recorded : VersionResolution.fromJSON(input.recorded);
+        const recordedKey = VersionWorkspaceKey.of(recorded).value;
+        if (current === undefined)
+            return {
+                action: "refuse",
+                reason: "unresolved",
+                workspace: name,
+                message: `Workspace ${name} was created with versions ${recordedKey}; resume it from a run that resolves its versions (the lab's version policy), never without them.`,
+            };
+        const key = VersionedWorkspace.keyOf(name);
+        if (key !== undefined && key !== recordedKey)
+            return {
+                action: "refuse",
+                reason: "misnamed",
+                workspace: name,
+                message: `Workspace ${name} records versions ${recordedKey}, not the ${key} its name carries; it was renamed or edited. Refusing to resume it.`,
+            };
+        const decision = RecoveryPolicy.decide({ recorded, current });
+        if (decision.action === "resume")
+            return { action: "resume", workspace: name };
+        const forCurrent = VersionedWorkspace.select(VersionedWorkspace.baseOf(name), current);
+        return {
+            ...decision,
+            workspace: name,
+            workspaceForCurrent: forCurrent,
+            message: decision.message.split(decision.workspaceForCurrent).join(forCurrent).split(`workspace ${decision.workspace}`).join(`workspace ${name}`),
+        };
+    }
+    static baseOf(name) {
+        return VERSIONED.exec(name)?.[1] ?? name;
+    }
+}