🥮 mooncakes.io

    morphir-metadata

    Scoped target-name fact interpretation with explicit provider admission

    Download zip
    Author
    Version
    0.1.0
    License
    Apache-2.0
    Repository
    Last updated
    4 days ago
    Downloads
    54

    #Morphir target-name metadata

    finos/morphir-metadata interprets a bounded naming adapter in rich engine metadata. It has no filesystem, network or process access. It preserves authored Ion values; its result records consumed assertions separately from the original data.

    The contract follows the finos/morphir linked-metadata draft and fixed reference cases at 23e7dfa4202d45fe74ef05e5214c0890125325d6. Local tests use independent expectations. They do not qualify native IR 4.1, an Ion IR profile, JSON-LD or the upstream MCK.

    #Selected declaration

    The consumer selects this production binding, distinct from upstream acme fixtures:

    morphir://ir/pkg/morphir/naming?format=4.1.0#/module/naming/value/target-names

    This binding requires a host-supplied authenticated provider. This repository does not ship a signed provider release or a signature verifier. The fixtures package simulates host restoration for tests; it is never an automatic provider source.

    Provider contractRequired declaration
    DistributionFreshly authenticated signed morphir/naming Library, native format 4.1.0
    DeclarationPublic naming module with public target-names ValueDefinition
    Output typeClosed record with exactly frontend and backend, both Dict String String
    Native schema factssubject-role = ValueDefinition, object-form = data, interpreter = target-name-language-ids
    Schema vocabularymorphir://ir/pkg/morphir/metadata?format=4.1.0#/module/schema/value/
    IdentityExact restored SHA-256 revision and matching revision-pinned distribution URI

    The schema facts must occur in the restored provider's own document $meta.@graph and name its declaration as subject. A companion schema file cannot replace them. A predicate URI may pin rev=sha256:<digest>; the restored revision must match. Every interpretation run invokes the restoration capability anew. Restores are reused only for equal expanded predicates within that run. A digest alone never authorizes a provider.

    RestoredLibrary.core is the supported semantic projection of the restored Library. The host must supply its native $meta and authenticated identity together. The core's current 4.0 codec is not used to claim a native 4.1 restore. The host is responsible for fresh signature authentication and for deriving the projection from those same bytes.

    #Engine adapter and authored assertions

    Store this payload in one owned IRUnit.metadata entry. Its annotation selects the adapter; arbitrary other metadata stays opaque. The local node_id is the engine storage holder. document identifies the containing assertion document, and each @id identifies a semantic subject. Those identities can differ.

    morphir_linked_metadata_v1::{
  document: "morphir://ir/pkg/example/annotations?format=4.1.0#/distribution",
  '$meta': {
    '@context': {
      targetNames: {
        '@id': "morphir://ir/pkg/morphir/naming?format=4.1.0#/module/naming/value/target-names",
        '@type': "@json"
      }
    },
    '@graph': [{
      '@id': "morphir://ir/pkg/example?format=4.0.0#/module/main/value/ready",
      targetNames: {
        frontend: {moonbit: "isReady"},
        backend: {moonbit: "chosen"}
      }
    }]
  }
}

    Only current, unpinned ValueDefinition subjects in the input Library are consumed. Body, attribute, type, specification, workspace and ordered-child subjects are outside this consumer's supported role. Native ValueDefinition facts belong in $meta.@graph; putting them on a body expression changes their subject. This envelope is an engine adapter, not a native carrier or a new IR format. The current JSON loss guard stays intact.

    Both maps are required; empty maps are valid. Language IDs follow ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$. Spelling strings stay opaque, including URI-looking text. The MoonBit generator separately checks backend.moonbit as a target identifier. Equal authored assertions retain separate holder/document/carrier/property/ordinal receipts. Contradictory records fail with their owner and contributing documents. assertionSources selectors must match expanded assertions from the same document and supply one complete, nonempty source set. Authored sources remain in the original payload; source claims are not authentication evidence.

    #Context acquisition and scope

    Contexts follow artifact then document scope. This slice consumes document graphs; node attributes and specification annotations are not projected by this adapter. Inline contexts, compact prefixes, exact aliases and canonical @vocab are supported. Narrow scopes can replace unprotected aliases; protected bindings cannot be replaced. Unsupported JSON-LD keywords fail before any result leaves the interpreter.

    A context reference is a relative .jsonld path or morphir://context/sha256/<64 lowercase hex digits>. References never cause HTTP fetches. contextBase can carry a file-base hint for relative imports. The explicit host loader must confine paths to its accepted workspace or verified archive root, resolve symlinks, inventory exact bytes and reject escape. A metadata-supplied base cannot widen that root. The portable consumer checks SHA-256 bytes before parsing, rejects cycles and repeated resources, and rejects conflicting imports before a trailing override. Content-addressed contexts have no relative file base.

    Bounds are 32 import levels, 256 resources per closure, 1 MiB per context document, and 100,000 expanded assertions per graph. Context files must be UTF-8 JSON with exactly one @context member and no duplicate object members.

    #Host capabilities

    Pass Capabilities to interpret, generate(metadata_capabilities=...), or Engine::new(metadata_capabilities=...). Capabilities are supplied by application code. Metadata and CLI configuration cannot install a restoration callback.

    The defaults have no provider or context loader and no required naming interpreter. Generation fails clearly on a known naming fact without provider declaration validation or interpretation; it never silently substitutes an automatic spelling. The installed CLI currently has no signed-Library restore integration. It can preserve these payloads in checkpoints, but cannot generate from known naming facts until a host integrates that service. Unknown syntactically valid predicates remain preserved and are listed as unvalidated.

    moon test -p finos/morphir-metadata --target all

    The shared v4.1-document-metadata-to-v4.0/1 projection is qualified against a signed test naming Library in finos/morphir-rust. Its authority-qualified release is example.com/morphir/naming@1.0.0; its native IR identity remains morphir/naming at 4.1.0. The interoperability test reads the shared v4.0 core view, original native document metadata and exact context bytes, then validates the closed frontend/backend declaration through a simulated host capability. The provider revision hashes the original native payload, not the core view.

    This qualifies data interoperability. Fresh authentication and restoration are verified separately by the Rust signed-fixture tests; installed host sessions and process transport remain separate integration work. The first projection profile refuses node-local linked metadata and nonlexical parameter maps.

    The shared signed fixture pins the source corpus used by the consumer test.

    #Observing provider declaration validation

    Capabilities.provider_observer receives Started, Succeeded, Refused(code) or Cancelled for declaration validation after restoration. The observer receives no provider data and grants no authority. Its exceptions are contained, preserving the original validation result and diagnostic. No facts means no restoration or validation events.

    When constructing capabilities explicitly, use { ..Capabilities::unavailable(), ... } to keep the no-op observer, or supply ProviderObserver::noop(). Hosts can attach their own bounded telemetry adapter without adding clocks or filesystem access to this pure package.

    is_target_names_predicate recognizes the supported declaration identity and optional native revision pin. It does not authorize a provider or assert that the pin matches. Process hosts use this same parser before restoration; pure validation compares the authored pin with the freshly authenticated native revision and retains metadata.provider_revision_mismatch on disagreement.

    MetadataError

    source
    pub(all) suberror MetadataError {
      Invalid(String, String, String)
    } derive(Eq, 
    Debug    )

    MetadataError::equal

    source

    MetadataError::not_equal

    source
    fn MetadataError::not_equal(x : MetadataError, y : MetadataError) -> Bool

    MetadataError::to_repr

    source

    Assertion

    source
    pub(all) struct Assertion {
      holder : String
      document : String
      carrier : String
      subject : String
      predicate : String
      property : String
      ordinal : Int
      object_ordinal : Int
    }

    Each authored carrier stays in the original Ion payload. This identifies the assertion consumed by this interpreter, not a new authored assertion.

    Capabilities

    source
    pub(all) struct Capabilities {
      restore_library : (String) -> RestoredLibrary raise?
      load_context : (String, String) -> ContextDocument raise?
      target_names_interpreter : Bool
      provider_observer : ProviderObserver
    }

    Host capabilities perform authenticated Library restoration and bounded context acquisition. A digest checks context bytes; it does not admit a provider.

    Capabilities::unavailable

    source
    fn Capabilities::unavailable() -> Capabilities

    ContextDocument

    source
    pub(all) struct ContextDocument {
      url : String
      bytes : Bytes
      sha256 : String
    }

    Interpretation

    source
    pub(all) struct Interpretation {
      facts : Array[NamingFact]
      unvalidated_predicates : Array[String]
    }

    MetadataEntry

    source
    pub(all) struct MetadataEntry {
      node_id : String
      data : 
    Ion
    }

    NamingFact

    source
    pub(all) struct NamingFact {
      owner : String
      names : TargetNames
      assertions : Array[Assertion]
      provider_revision : String
    }

    ProviderObserver

    source
    pub(all) struct ProviderObserver {
      notify : (ProviderSignal) -> Unit raise
    }

    Notification failures are contained. Observations cannot change admission.

    ProviderObserver::noop

    source

    ProviderSignal

    source
    pub(all) enum ProviderSignal {
      Started
      Succeeded
      Refused(String)
      Cancelled
    } derive(Eq, 
    Debug    )

    Declaration admission events carry no provider payload or authority.

    ProviderSignal::equal

    source

    ProviderSignal::not_equal

    source
    fn ProviderSignal::not_equal(x : ProviderSignal, y : ProviderSignal) -> Bool

    ProviderSignal::to_repr

    source

    RestoredLibrary

    source
    pub(all) struct RestoredLibrary {
      core : 
    IRFile
      format : String
      revision : String
      document : String
      document_metadata : 
    Ion
    }

    The trusted host must freshly authenticate and restore the signed Library before returning this projection. The core has no signature verifier or ambient registry. Wire metadata cannot supply this capability. core is the supported semantic projection; format is the native release.

    TargetNames

    source
    pub(all) struct TargetNames {
      frontend : Map[String, String]
      backend : Map[String, String]
    } derive(Eq, 
    Debug    )

    TargetNames::equal

    source
    fn TargetNames::equal(TargetNames, TargetNames) -> Bool

    TargetNames::from_ion

    source
    fn TargetNames::from_ion(value : 
    Ion    , owner? : String, language_ids? : Bool) -> TargetNames raise

    One closed typed data object, with both maps required. Empty maps are valid.

    TargetNames::not_equal

    source
    fn TargetNames::not_equal(x : TargetNames, y : TargetNames) -> Bool

    TargetNames::to_repr

    source

    ADAPTER_PROFILE

    source
    let ADAPTER_PROFILE : String

    TARGET_NAMES_PREDICATE

    source
    let TARGET_NAMES_PREDICATE : String

    interpret

    source
    fn interpret(file : 
    IRFile    , unit_id : String, entries : Array[MetadataEntry], capabilities? : Capabilities, owned? : Map[String, Bool]) -> Interpretation raise

    Interpret the explicit engine adapter without changing any authored Ion. This is not a native IR 4.1/Ion codec or a general JSON-LD processor. A caller that has the node identities of file and unit_id already, as @identities.nodes gives them, passes them as owned, so that they are not collected again.

    is_target_names_predicate

    source
    fn is_target_names_predicate(uri : String) -> Bool raise

    Recognize the 4.1 target-names declaration, including optional native revision pins. Recognition grants no authority and does not check revision equality; admission checks the pin against the freshly restored native Library.

    valid_language_id

    source
    fn valid_language_id(value : String) -> Bool

    value_uri

    source

    Source Files