Skip to content

graflo.architecture.evolution.aspects.provenance.plan

Planning the provenance aspect: SourceRecord, Agent and their edges.

A pure planner over the same op vocabulary as every other manifest change. It needs no spec: which types read their facts from a source record and which a record can name are all a caller may add, and the composed lift adds the state and observation scaffolds to the first list itself.

Attributes

__all__ = ['plan_provenance'] module-attribute

Classes

Functions:

plan_provenance(manifest, *, attach=(), mentions=())

The ops that make lineage expressible in manifest.

SourceRecord -wasAttributedTo-> Agent is emitted even when there is nothing else to attach: it is what makes the schema able to say where a fact came from, which is the question the world-model profile asks.

The vocabulary is joined with what the manifest has (:func:~graflo.architecture.evolution.aspects.join.join): a SourceRecord or Agent it already declares keeps its own properties and gains the aspect's missing ones, so manifests that carry the vocabulary, such as source kits, compose and lift in any order.

Parameters:

Name Type Description Default
manifest GraphManifest

the manifest to lift, already finish_init()-ed.

 required
attach Iterable[str]

vertex type names that gain a wasDerivedFrom edge to SourceRecord, in this order. The caller vouches that each one exists or is added by the same change set.

 ()
mentions Iterable[str]

vertex type names SourceRecord gains a mentions edge to, in this order, on the same terms.

 ()

Raises:

Type Description
LiftError

the manifest has no schema, or declares part of the vocabulary in a way that contradicts it.
Source code in graflo/architecture/evolution/aspects/provenance/plan.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
def plan_provenance(
    manifest: GraphManifest,
    *,
    attach: Iterable[str] = (),
    mentions: Iterable[str] = (),
) -> list[ManifestOp]:
    """The ops that make lineage expressible in *manifest*.

    ``SourceRecord -wasAttributedTo-> Agent`` is emitted even when there is
    nothing else to attach: it is what makes the schema *able* to say where a
    fact came from, which is the question the world-model profile asks.

    The vocabulary is joined with what the manifest has
    (:func:`~graflo.architecture.evolution.aspects.join.join`): a
    ``SourceRecord`` or ``Agent`` it already declares keeps its own properties
    and gains the aspect's missing ones, so manifests that carry the
    vocabulary, such as source kits, compose and lift in any order.

    Args:
        manifest: the manifest to lift, already ``finish_init()``-ed.
        attach: vertex type names that gain a ``wasDerivedFrom`` edge to
            ``SourceRecord``, in this order. The caller vouches that each one
            exists or is added by the same change set.
        mentions: vertex type names ``SourceRecord`` gains a ``mentions`` edge to,
            in this order, on the same terms.

    Raises:
        LiftError: the manifest has no schema, or declares part of the
            vocabulary in a way that contradicts it.
    """
    schema = manifest.graph_schema
    if schema is None:
        raise LiftError(
            "cannot lift a manifest with no schema block: there are no types to "
            "attach provenance to"
        )
    return join(
        schema.core_schema,
        vertices=[vocab.source_record_vertex(), vocab.agent_vertex()],
        edges=[
            *(vocab.derived_from_edge(name) for name in attach),
            *(vocab.mentions_edge(name) for name in mentions),
            vocab.attributed_to_edge(),
        ],
    )