Primitive Library

grant

Issue an access grant on a record (atom/verb/lexeme/pixel). The grant widens access for actors matching its rule. Caller must be able to manage the subject.

revoke

Revoke (soft-delete) an access grant. Caller must be the grant issuer or a manager of the subject record.

concat

Concatenate an array of arrays into a single new array.

contains

Check whether an array contains a value using primitive equality.

create

Return a new array from provided items. Supports mixed literals and pre-resolved values.

filter

Filter an array of objects by a value at a key path. With `contains` (case-insensitive substring) or `equals` (exact). An empty/absent criterion returns the array unchanged, so a blank query is a no-op.

filterNullish

Return a new array without null and undefined values.

length

Return the length of an array.

project

Project each element of an array into a new object by mapping output keys to source path(s), with first-present fallback and defaults. Lets a read verb shape an atom list into display rows.

push

Return a new array with a single value or multiple items appended to the end.

remove

Return a new array with one element removed by value or by index.

sort

Sort an array of objects or primitive values by one or more key paths.

unique

Return a new array with duplicate values removed, preserving first-seen order.

appendDataField

System primitive that appends a single FieldEntry to an atom's data map. Fails if the field name already exists (use a separate update primitive to overwrite).

assignLexeme

System primitive that assigns one lexeme to an existing atom. Idempotent: already-assigned lexemes are no-ops.

create

System primitive that creates an atom with optional initial data, lexemeIds, and visibility.

delete

System primitive that soft-deletes one atom.

findByDataCriteria

List atoms by top-level data field presence and optional primitive value equality.

findOrCreate

Idempotently return the caller's own atom matching `matchData`, creating it from `data`/`lexemeIds` when absent. Concurrent duplicate creates collapse to a single atom via the owner+namespace+slug partial unique index.

findOrCreateDataField

Create a data field when missing, otherwise update it, while reusing append/update primitive behavior.

getDataField

System primitive that returns one top-level atom.data field value without requiring full-atom handling in composed verbs.

list

System primitive that queries atoms visible to the authenticated user. Supports filtering by lexeme, scope, visibility, and organization. Returns a paginated array of serialized atoms.

listShares

System primitive that lists share grants for one atom.

query

System primitive that queries atoms with constrained matcher filters and caller-selected sort.

read

System primitive that reads a single atom and returns the public-safe serialized shape.

removeDataField

System primitive that removes one field key from an atom data map.

restore

System primitive that restores a soft-deleted atom.

setNestedDataField

Sets a nested FieldEntry under atom.data using a string[] path. Missing intermediate object entries are created automatically.

setPublic

System primitive that toggles atom-level isPublic.

share

System primitive that adds or updates one atom share grant.

snapshot

Sandbox-only primitive that clones an existing atom into the current sandbox session. Used by the verb editor's Test Run panel so a preview verb can mutate a copy of real (PRD) data without touching the original. The clone is owned by the caller, stamped with the sandbox marker, and carries the source atom id and version for diff display.

transferOwnership

System primitive that transfers atom ownership to a user or organization atom.

unassignLexeme

System primitive that removes one lexeme subscription from an atom.

unshare

System primitive that removes one atom share grant.

updateDataField

System primitive that overwrites an existing FieldEntry on an atom data map.

updateDataFields

System primitive that writes a bag of top-level atom.data fields by delegating each key to atom.findOrCreateDataField. This is a sequential loop and not a single-document atomic update across all keys.

match

Pure predicate: evaluates a matcher expression against a candidate object and returns whether it matched.

addMember

Create a collection membership atom for (collectionRef, targetType, targetId).

archive

Soft-archive a collection by setting data.archived=true.

create

Create a collection atom subscribed to system.lexeme.collection.

list

List collections visible to the caller, including personal and organization-visible collections.

members

List active members for a collection.

membershipsForTarget

List visible collection memberships for a target record.

read

Read one collection by atom id.

removeMember

Soft-delete a collection membership atom by tuple.

unassigned

List visible records of one targetType that have no active collection membership.

update

Update mutable collection fields by collection id.

coalesce

Return the first non-null and non-undefined value from an array.

fromJson

Parse JSON text into a value.

merge

Shallow merge right object onto left object.

omit

Return a shallow object excluding requested keys.

pick

Return a shallow object containing only requested keys.

toJson

Serialize a value to JSON text.

validateArrayElements

Validate that every element in an array matches a selected built-in validator.

validateEnum

Validate that a value is included in an allowed primitive-value set.

validateObjectShape

Validate object key shape against requiredKeys and allowedKeys constraints.

validatePattern

Validate that a string matches a provided regular expression.

validateRange

Validate that a numeric value is within optional min/max bounds.

validateRequired

Validate that a value is present (not null/undefined), with optional empty-string allowance.

validateStringLength

Validate that a string length is within optional min/max bounds.

validateType

Validate that a value matches an expected primitive classifier.

addField

System primitive that appends one field definition.

create

System primitive that creates a lexeme.

delete

System primitive that soft-deletes a lexeme.

list

System primitive that returns lexemes visible to the caller.

listAtoms

System primitive that lists atoms for a readable lexeme.

listShares

System primitive that lists share grants for one lexeme.

read

System primitive that reads one lexeme by id.

removeField

System primitive that removes one lexeme field definition.

restore

System primitive that restores a soft-deleted lexeme.

setCategory

System primitive that assigns or clears top-level lexeme category reference.

share

System primitive that adds or updates a lexeme share grant.

snapshot

Sandbox-only primitive that clones an existing lexeme into the current sandbox session. Used by the verb editor's Test Run panel so a preview verb can mutate a copy of real (PRD) lexeme data without touching the original. The clone is owned by the caller, stamped with the sandbox marker, and carries the source lexeme id and version for diff display.

transferOwnership

System primitive that transfers lexeme ownership to a user or organization atom.

unshare

System primitive that removes a lexeme share grant.

update

System primitive that updates lexeme top-level attributes.

and

Return true when all values are truthy.

assert

Throw a typed error when condition is not strictly true.

equals

Deep equality for primitives, arrays, and plain objects.

if

Pick thenValue or elseValue based on condition truthiness.

not

Return logical negation of a value.

or

Return true when any value is truthy.

abs

Return absolute value.

add

Sum an array of numbers.

clamp

Clamp a value within inclusive min and max bounds.

divide

Divide a by b.

max

Return the maximum value from a non-empty number array.

min

Return the minimum value from a non-empty number array.

multiply

Multiply an array of numbers.

round

Round a value to a precision using round, floor, or ceil mode.

subtract

Subtract b from a.

create

Create a plain object from key/value entries, rejecting duplicate keys.

entries

Return top-level own entries of a plain object.

has

Check whether a plain object has a top-level own key.

keys

Return top-level own keys of a plain object.

merge

Merge an array of plain objects with configurable conflict handling.

omit

Return a shallow object excluding requested keys, similar to data.omit.

pick

Return a shallow object containing only requested keys, similar to data.pick.

set

Return a new plain object with a top-level key set to a value.

assertCurrentUserHas

Advisory permission check for the current user based on a license atom. Returns allowed=false instead of throwing for negative checks.

assertOrgRole

Assert that the current user has the required effective role for an organization.

findCurrentUserLicenseAtom

Finds the current user's license atom through the standard atom list/read path and returns a serialized atom or null.

grantOrgRole

Grant an org role by creating (or reusing) an active org-role-grant atom.

revokeOrgRole

Revoke an active org role grant for a user in an organization.

create

System primitive that creates a pixel contract.

list

System primitive that returns pixels visible to the caller.

listShares

System primitive that lists share grants for one pixel.

read

System primitive that reads one pixel by id.

setCategory

System primitive that assigns or clears top-level pixel category reference.

transferOwnership

System primitive that transfers pixel ownership to a user or organization atom.

update

System primitive that updates a pixel contract.

validate

Validate a pixel contract without saving or changing any platform data.

decrypt

Admin-only: decrypts a sensitive-field envelope under a specified owner KEK. Prefer secret.reveal for application use.

encrypt

Encrypts a JSON value into a sensitive-field envelope (SOCIALLUX_THEORY §13).

reveal

Authorizes and decrypts a single sensitive field on a single atom. Emits a `secret.revealed` audit event.

rewrap

Re-wraps every sensitive envelope on an atom under a new owner KEK without re-encrypting ciphertext (SOCIALLUX_THEORY §13.3).

concat

Join an array of values into a single string with an optional separator.

format

Substitute {{key}} placeholders in a template with values from a provided object.

includes

Check whether text includes, starts with, or ends with search text.

length

Return the character length of text.

lower

Convert text to lowercase.

replace

Perform literal find-and-replace on a string.

split

Split text into an array using a literal separator.

trim

Trim leading and trailing whitespace from text.

upper

Convert text to uppercase.

extract

Extract a permission-trimmed surface.v1 manifest for a collection within an organization.

publish

Publish a stable surface snapshot atom with canonical manifest hash and previous snapshot link.

add

Add a time amount to an instant.

compare

Compare two instants and return -1, 0, or 1.

diff

Return signed time delta from one instant to another.

format

Format an instant as ISO, unix, date, or time output.

now

Return the current instant in ISO or unix formats.

fire

Fire a single trigger atom against an originating AuditEvent, applying matcher/self-loop/depth guards.

findByEmail

System primitive that looks up a share-target user by email.

findById

System primitive that looks up a share-target user by ObjectId.

listOrganizationMembers

System primitive that lists organization members and effective org roles.

me

System primitive that returns auth/me-equivalent user context.

whoami

System primitive that returns a summary of the calling user.

isEmpty

Return true for null/undefined/empty string/empty array/empty object.

typeOf

Return a normalized type discriminator.

contract

Returns a developer-facing contract for a verb: how to call it, the inputs it needs, the output shape, and an example invocation.

create

System primitive that creates a user-authored verb definition.

list

System primitive that returns verbs visible to the caller.

listShares

System primitive that lists share grants for one verb.

read

System primitive that reads one verb by id.

setCategory

System primitive that assigns or clears top-level verb category reference.

transferOwnership

System primitive that transfers verb ownership to a user or organization atom.

update

System primitive that updates a user-authored verb definition.