Skip to main content

raf_source/workspace/locked/
reference.rs

1// SPDX-FileCopyrightText: 2026 Blackcat InformaticsĀ® Inc. <paudley@blackcatinformatics.ca>
2// SPDX-License-Identifier: MIT OR Apache-2.0 OR MulanPSL-2.0
3
4//! Declaration-qualified reference observations, separate from provider admission.
5
6use super::super::{Caches, Reader, WorkspaceOf, package_directory_index, workspace_of};
7use super::{BindingLoad, Hint, LockedBinding, failure, native, recover};
8use crate::meter::{ItemAdmission, Meter};
9use crate::{
10    CommittedGitTree, DependencyDeclaration, LoadError, LoadOptions, LockedCatalog,
11    LockedPackageId, LockedSource, LockedSourceKind, PackageId, RegistryIndex, RelPath, Tree,
12    Workspace,
13};
14use purrdf_lex::allocation::Memory;
15
16fn iri_failure(manifest: &RelPath, error: purrdf_iri::IriReadError) -> LoadError {
17    match error {
18        purrdf_iri::IriReadError::Storage(error) => native(error),
19        purrdf_iri::IriReadError::Lexical(error) => failure(manifest, &error.to_string()),
20    }
21}
22
23fn manifest_image(
24    tree: &dyn Tree,
25    manifest: &RelPath,
26    meter: &Meter,
27) -> Result<RelPath, LoadError> {
28    if !manifest.segments().any(|segment| segment == "..") {
29        return Ok(manifest.clone());
30    }
31    directory_prefixes(tree, manifest, meter)?;
32    meter.work(
33        manifest
34            .as_str()
35            .len()
36            .saturating_mul(64)
37            .saturating_add(128),
38        manifest,
39        None,
40    )?;
41    let mut admission = ItemAdmission::new(meter, manifest);
42    let result = (|| {
43        let mut memory = Memory::new(&mut admission);
44        let encoded = purrdf_lex::percent::encode_with_memory(
45            manifest.as_str(),
46            purrdf_lex::percent::UNRESERVED_SLASH,
47            &mut memory,
48        )
49        .map_err(native)?;
50        let base = purrdf_iri::parse_with_memory("https://reference.invalid/", &mut memory)
51            .map_err(|error| iri_failure(manifest, error))?;
52        let resolved = base
53            .resolve_with_memory(&encoded, &mut memory)
54            .map_err(|error| iri_failure(manifest, error))?;
55        let path = resolved
56            .path()
57            .strip_prefix('/')
58            .ok_or_else(|| failure(manifest, "native manifest image lost its source root"))?;
59        // Native decoding and the retained RelPath each fit this admitted
60        // upper bound; percent decoding cannot increase the encoded byte count.
61        meter.items(
62            crate::cost::shared_text(path.len()).saturating_mul(2),
63            manifest,
64            None,
65        )?;
66        let decoded = purrdf_lex::percent::decode(path)
67            .map_err(|error| failure(manifest, &error.to_string()))?;
68        RelPath::new(&decoded)
69            .map(|path| path.in_source(manifest.authority()))
70            .map_err(|error| failure(manifest, &error.to_string()))
71    })();
72    let image = result.map_err(|error| recover(error, &mut admission))?;
73    let identity = |path: &RelPath| {
74        tree.identity(path)
75            .map_err(|error| LoadError::tree(path, None, &crate::error::Origin::Discovery, error))
76    };
77    if identity(manifest)? != identity(&image)? {
78        return Err(failure(
79            manifest,
80            "parent path and native source-relative image name different files; supply an explicit manifest locator",
81        ));
82    }
83    Ok(image)
84}
85
86fn directory_prefixes(tree: &dyn Tree, manifest: &RelPath, meter: &Meter) -> Result<(), LoadError> {
87    let directory = manifest
88        .parent()
89        .ok_or_else(|| failure(manifest, "manifest has no source directory"))?;
90    let mut prefix = manifest.source_root();
91    for segment in directory.segments() {
92        let bytes = prefix
93            .as_str()
94            .len()
95            .saturating_add(segment.len())
96            .saturating_add(1);
97        meter.work(bytes.saturating_mul(2), manifest, None)?;
98        meter.items(crate::cost::shared_text(bytes), manifest, None)?;
99        prefix = prefix
100            .join(segment)
101            .map_err(|error| failure(manifest, &error.to_string()))?;
102        match tree.entry(&prefix).map_err(|error| {
103            LoadError::tree(&prefix, None, &crate::error::Origin::Discovery, error)
104        })? {
105            Some(crate::EntryKind::Dir) => {}
106            Some(crate::EntryKind::Symlink) => {
107                return Err(failure(
108                    &prefix,
109                    "parent traversal crosses a directory symlink; supply an explicit manifest locator",
110                ));
111            }
112            _ => {
113                return Err(failure(
114                    &prefix,
115                    "original manifest directory prefix is not a real directory",
116                ));
117            }
118        }
119    }
120    Ok(())
121}
122
123/// One actual manifest declaration and its exact owning lock row.
124pub struct ReferenceRequest<'a> {
125    catalog: &'a LockedCatalog,
126    owner: LockedPackageId,
127    declaration: &'a DependencyDeclaration,
128    registry: Option<RegistryIndex<'a>>,
129}
130
131impl<'a> ReferenceRequest<'a> {
132    /// Resolve the written alias, inherited constraints and source against this catalog.
133    #[must_use]
134    pub const fn new(
135        catalog: &'a LockedCatalog,
136        owner: LockedPackageId,
137        declaration: &'a DependencyDeclaration,
138    ) -> Self {
139        Self {
140            catalog,
141            owner,
142            declaration,
143            registry: None,
144        }
145    }
146
147    /// Supply the explicitly observed index for a named or default registry.
148    #[must_use]
149    pub const fn registry(mut self, registry: RegistryIndex<'a>) -> Self {
150        self.registry = Some(registry);
151        self
152    }
153
154    /// Select exactly one complete outgoing row, without acquiring its contents.
155    ///
156    /// # Errors
157    /// Preserves missing, ambiguous, incompatible and resource refusals from the catalog.
158    pub fn select(&self, options: &LoadOptions) -> Result<LockedPackageId, LoadError> {
159        self.select_with_usage(options).map(|(row, _)| row)
160    }
161
162    /// Select one outgoing row and report its actual bounded selection usage.
163    ///
164    /// Work covers declaration/source/version comparisons. Item usage includes
165    /// the retained catalog allowance; it is not newly acquired source storage.
166    /// No source file is loaded and no provider authority is admitted.
167    ///
168    /// # Errors
169    /// Preserves the same catalog and resource refusals as [`Self::select`].
170    pub fn select_with_usage(
171        &self,
172        options: &LoadOptions,
173    ) -> Result<(LockedPackageId, crate::Usage), LoadError> {
174        let meter = Meter::new(options);
175        let row = self.select_under(&meter, &RelPath::root())?;
176        Ok((row, meter.usage()))
177    }
178
179    fn select_under(
180        &self,
181        meter: &Meter,
182        manifest: &RelPath,
183    ) -> Result<LockedPackageId, LoadError> {
184        meter.items(self.catalog.usage().item_bytes, manifest, None)?;
185        self.catalog
186            .select_under(self.owner, self.declaration, self.registry, meter)
187    }
188}
189
190/// A read-only reference package whose manifest matches its selected lock identity.
191///
192/// Local and registry contents are observations of the supplied contained Tree,
193/// not archive authentication. Git contents require the sealed committed backend.
194/// The loaded workspace deliberately retains no locked bindings, configured
195/// dependency edges or preferred-provider admission.
196pub struct ReferenceObservation {
197    workspace: Workspace,
198    identity: LockedBinding,
199    checksum: Option<[u8; 32]>,
200}
201
202/// The explicit or inherited `[package] version` of discovered package zero,
203/// `None` when the manifest sets none.
204fn declared_version(
205    tree: &dyn Tree,
206    meter: &Meter,
207    discovered: &crate::discovery::Discovered,
208    manifest: &RelPath,
209) -> Result<Option<String>, LoadError> {
210    let found = &discovered.packages[0];
211    let dirs = package_directory_index(&discovered.packages, meter)?;
212    let reader = Reader {
213        tree,
214        meter,
215        dirs: &dirs,
216        found: &discovered.packages,
217    };
218    Ok(match &found.declared.version {
219        crate::manifest::VersionDecl::Explicit(version) => Some(version.clone()),
220        crate::manifest::VersionDecl::Inherited => {
221            match workspace_of(&reader, &found.package.dir, &mut Caches::default())? {
222                WorkspaceOf::Member {
223                    version: Some(version),
224                    ..
225                } => Some(version.as_str().to_owned()),
226                _ => {
227                    return Err(failure(
228                        manifest,
229                        "local package version has no admitted workspace value",
230                    ));
231                }
232            }
233        }
234        crate::manifest::VersionDecl::Unset => None,
235    })
236}
237
238impl ReferenceObservation {
239    /// Observe one actual local root package and associate its explicit or
240    /// inherited version with a unique source-less lock row. This is the owning
241    /// manifest context for subsequent declaration-qualified reference requests.
242    ///
243    /// # Errors
244    /// Refuses missing/ambiguous lock identity, invalid inheritance and bounded
245    /// source failures. No provider admission is retained.
246    pub fn local_root(
247        catalog: &LockedCatalog,
248        tree: &dyn Tree,
249        manifest: &RelPath,
250        options: &LoadOptions,
251    ) -> Result<Self, LoadError> {
252        let meter = Meter::new(options);
253        meter.items(catalog.usage().item_bytes, manifest, None)?;
254        let image = manifest_image(tree, manifest, &meter)?;
255        let discovered = crate::discovery::single(tree, &image, &meter)?;
256        let found = &discovered.packages[0];
257        let version = declared_version(tree, &meter, &discovered, manifest)?.ok_or_else(|| {
258            failure(
259                manifest,
260                "local package needs explicit or inherited version evidence",
261            )
262        })?;
263        let version = version.as_str();
264        let mut selected = None;
265        for row in catalog.packages() {
266            let comparison = row
267                .name()
268                .len()
269                .saturating_add(found.declared.name.len())
270                .saturating_add(row.version().len())
271                .saturating_add(version.len())
272                .saturating_add(1);
273            meter.work(comparison, manifest, None)?;
274            if row.source().is_some()
275                || row.name() != found.declared.name
276                || row.version() != version
277            {
278                continue;
279            }
280            if selected.replace(row.id()).is_some() {
281                return Err(failure(
282                    manifest,
283                    "actual local manifest matches multiple lock rows",
284                ));
285            }
286        }
287        let row = selected.ok_or_else(|| {
288            failure(
289                manifest,
290                "actual local manifest name/version has no matching lock row",
291            )
292        })?;
293        Self::observe_discovered(catalog, row, tree, &meter, &discovered)
294    }
295    /// Observe a local or registry package through the ordinary bounded source loader.
296    /// The manifest is relative to the supplied Tree, whose root must retain any
297    /// workspace manifest needed for inherited package fields.
298    ///
299    /// # Errors
300    /// Refuses unresolved declarations, Git rows, mismatched manifests, extra
301    /// packages, invalid inheritance and all ordinary source/containment limits.
302    pub fn load(
303        request: &ReferenceRequest<'_>,
304        tree: &dyn Tree,
305        manifest: &RelPath,
306        options: &LoadOptions,
307    ) -> Result<Self, LoadError> {
308        let meter = Meter::new(options);
309        let row = request.select_under(&meter, manifest)?;
310        if request
311            .catalog
312            .package(row)
313            .and_then(|row| row.source())
314            .is_some_and(|source| source.kind() == LockedSourceKind::Git)
315        {
316            return Err(failure(
317                manifest,
318                "a Git reference requires its sealed committed Tree",
319            ));
320        }
321        Self::observe(request.catalog, row, tree, manifest, &meter)
322    }
323
324    /// Observe the exact committed source selected by the declaration and lock row.
325    ///
326    /// The returned workspace usage includes the protocol, listing and blob work
327    /// of this observation under its original selection/source allowance. The
328    /// caller's prior construction of the supplied Tree precedes this operation.
329    ///
330    /// # Errors
331    /// Refuses a different committed source and all bounded source/identity failures.
332    pub fn committed(
333        request: &ReferenceRequest<'_>,
334        tree: &CommittedGitTree<'_>,
335        manifest: &RelPath,
336        options: &LoadOptions,
337    ) -> Result<Self, LoadError> {
338        let meter = Meter::new(options);
339        let row = request.select_under(&meter, manifest)?;
340        if request.catalog.package(row).and_then(|row| row.source()) != Some(tree.source()) {
341            return Err(failure(
342                manifest,
343                "committed reference source differs from its selected lock row",
344            ));
345        }
346        // Caller-owned construction precedes this observation. Reopen its
347        // sealed source under this operation's original selection/load grant.
348        let observed = tree.under_meter(&meter)?;
349        Self::observe(request.catalog, row, &observed, manifest, &meter)
350    }
351
352    fn observe(
353        catalog: &LockedCatalog,
354        row: LockedPackageId,
355        tree: &dyn Tree,
356        manifest: &RelPath,
357        meter: &Meter,
358    ) -> Result<Self, LoadError> {
359        let image = manifest_image(tree, manifest, meter)?;
360        let discovered = crate::discovery::single(tree, &image, meter)?;
361        Self::observe_discovered(catalog, row, tree, meter, &discovered)
362    }
363
364    fn observe_discovered(
365        catalog: &LockedCatalog,
366        row: LockedPackageId,
367        tree: &dyn Tree,
368        meter: &Meter,
369        discovered: &crate::discovery::Discovered,
370    ) -> Result<Self, LoadError> {
371        let manifest = discovered.packages[0].package.manifest.clone();
372        let options = meter.options();
373        meter.items(crate::index::LOAD_BASE_BYTES, &manifest, None)?;
374        let mut admission = ItemAdmission::new(meter, &manifest);
375        let mut hints = Vec::new();
376        Memory::new(&mut admission)
377            .push(
378                &mut hints,
379                Hint {
380                    row,
381                    manifest: manifest.clone(),
382                    edges: &[],
383                    configuration: None,
384                },
385            )
386            .map_err(|error| admission.error(error))?;
387        let binding = BindingLoad {
388            catalog,
389            hints,
390            purpose: super::Purpose::Configured,
391        };
392        let mut workspace =
393            Workspace::build_discovered(tree, options, meter, Some(&binding), discovered)?;
394        let identity = workspace.locked.pop().ok_or_else(|| {
395            failure(
396                &manifest,
397                "reference manifest has no validated package identity",
398            )
399        })?;
400        // The one exact association was validated by bind_found. No provider
401        // proof or configured edge escapes through the reference workspace.
402        if !workspace.locked.is_empty() || workspace.packages.len() != 1 {
403            return Err(failure(
404                &manifest,
405                "a reference observation must select exactly one package",
406            ));
407        }
408        let checksum = catalog.package(row).and_then(|row| row.checksum()).copied();
409        Ok(Self {
410            workspace,
411            identity,
412            checksum,
413        })
414    }
415
416    /// Parsed source and declarations, without provider-admitted locked bindings.
417    #[must_use]
418    pub const fn workspace(&self) -> &Workspace {
419        &self.workspace
420    }
421
422    /// The selected package within this observation's own workspace.
423    #[must_use]
424    pub const fn package(&self) -> PackageId {
425        PackageId(0)
426    }
427
428    /// Selected identity within the request's catalog.
429    #[must_use]
430    pub const fn row(&self) -> LockedPackageId {
431        self.identity.row
432    }
433
434    /// Manifest-verified Cargo package name.
435    #[must_use]
436    pub fn name(&self) -> &str {
437        &self.identity.name
438    }
439
440    /// Actual explicit or inherited manifest version.
441    #[must_use]
442    pub fn version(&self) -> &str {
443        &self.identity.version
444    }
445
446    /// Complete external lock source, absent for a local path package.
447    #[must_use]
448    pub const fn source(&self) -> Option<&LockedSource> {
449        self.identity.source.as_ref()
450    }
451
452    /// Recorded registry archive checksum; this does not authenticate a supplied Tree.
453    #[must_use]
454    pub const fn checksum(&self) -> Option<&[u8; 32]> {
455        self.checksum.as_ref()
456    }
457}