# MeOS core specification Status: implemented baseline; requirements in [project contract](../project-contract.md) take precedence. File: private/meos/core.php. Tables: nodes, node_attributes, node_relationships, vectors, vector_attributes, vector_relationships, vector_node_relationships. Exact definitions: [core schema](../schema/core.sql). ## Model and invariants vector_id is binary UUID identity. timestamp is the event time, magnitude a nonnegative DECIMAL(20,4), and source_node_id/dest_node_id the endpoints. The primitive has no accounting columns. A capability interprets the endpoints and adds context externally. Node IDs are ASCII namespace paths up to 191 characters. Colon-separated segments establish explicit child_of relationships. Nodes have display names; JSON attributes and typed relationships are separate tables. The implementation uses paths for identity and subtree queries, not merely display labels. Core functions have no financial dependencies. PDO ownership and multi-operation transactions belong to the caller. No global application configuration is loaded here. ## Function contracts | Function | Behaviour | | --- | --- | | meos_uuid | Returns 16 random bytes with UUID v4/version and variant bits. Not a formatted UUID string. | | meos_json | JSON encoding with unescaped slashes and exceptions on failure. | | meos_rows | Prepared query and associative rows. | | meos_node | Validates path; inserts identity/name without replacing an existing name; inserts compatible attributes; recursively ensures ancestors and child_of links. | | meos_vector | Validates exact Y-m-d H:i:s timestamp, decimal magnitude with up to 16 whole digits and 4 decimals, endpoint existence, and matching unit attributes when both endpoints declare units. Inserts a new vector. | | meos_link_vectors | Valid relation key, no self-link; existing relationship is a no-op. Inserts external relationship. | | meos_link_nodes | Valid relation key, no self-link; inserts node relationship. | | meos_read_vectors | Prefix subtree lookup touching either endpoint, timestamp interval [from, until), sorted by timestamp and binary identity. Escapes LIKE wildcard characters in the namespace. | | meos_annotate_vector | Adds JSON annotations; same value is a no-op, changed existing value is rejected. | | meos_link_vector_node | Adds a contextual node relationship outside the primitive. | Relation keys match a lowercase letter followed by up to 63 lowercase letters, digits or underscores. Node paths accept letters, digits, underscores and hyphens in nonempty colon-separated segments. Read intervals must end after they begin. The core compares JSON values through decode/re-encode. Attribute compatibility should not be assumed to ignore associative key ordering. Existing node display names are not updated by meos_node. ## Storage protection Database triggers block updates/deletes on vectors, vector_relationships and vector_attributes. This protects existing events and annotations. Node and contextual relationship storage does not have the same complete set of immutability triggers. Do not claim stronger protection than the installed definitions provide. The DATETIME column does not encode timezone. The core validates syntax rather than performing timezone conversion. Accounting currently supplies statement-date midnight, separately recording UTC revision times. Do not treat these as the same timestamp semantics. ## Verification scenarios Reject missing endpoints, invalid dates, negative magnitudes, excess precision, conflicting endpoint units and changed annotations. Accept zero magnitude. Confirm no sixth vector column; update/delete triggers reject writes. Query boundaries include from and exclude until; underscores in namespace must not act as wildcards. Test core without Accounting/bootstrap loaded. See [Accounting adapter](../accounting/capability.md) for accounting interpretation rather than altering this specification.