@almadar/std 16.145.0 → 16.147.0

package/behaviors/lolo/infra/atoms/std-migration-job.lolo

@@ -0,0 +1,269 @@
+app std-migration-job "1.0.0"
+"std-migration-job — one import run of external data into the host system, modeled as a persistent MigrationJob row with a lifecycle state machine: idle → fetching → mapping → reviewing → committing → done | failed. All source access goes through the migration service (call-service \"migration\" listDocuments / fetchDocument / commit) — the atom never talks to a source directly, and the host-injected service handler resolves credentials from the connectionRef knob (a reference, never the secret). Staging/mapping is host work (deterministic pipeline or agent): the atom fetches, the host stages and emits MIGRATION_STAGED, the user approves (MIGRATION_APPROVED) and only then does commit run. Terminal runs persist the job row for provenance. Rebind the entity to a host-owned job entity via linkedEntity; target and connectionRef are config knobs."
+orbital MigrationJobOrbital {
+
+  entity MigrationJob [persistent: migration_jobs] {
+    id : string!
+    source : object @description "ImportSource descriptor of the run (kind + options), supplied by the host." = {}
+    files : [object] @description "Client-side file metadata for upload sources (name/size/type/lastModified)." = []
+    target : string @description "Name of the host entity this import writes into." = ""
+    status : "idle" | "fetching" | "mapping" | "reviewing" | "committing" | "done" | "failed" @description "Lifecycle position of the run." = idle
+    documents : [object] @description "Document metadata listed from the source." = []
+    document : object @description "Most recently fetched document content." = {}
+    stats : object @description "Staged/committed/failed/skipped counts." = {}
+    error : string @description "Failure detail when status is failed." = ""
+    createdAt : number @description "Run start timestamp." = 0
+  }
+
+  trait MigrationJobLifecycle -> @rebindable MigrationJob [lifecycle, instance] {
+    initial: idle
+
+    state idle {
+      INIT -> idle
+        (set @entity.status idle)
+        (set @entity.error "")
+        (set @entity.documents [])
+        (set @entity.document {})
+        (set @entity.stats {})
+      MIGRATION_START -> fetching
+        (set @entity.source ?source)
+        (set @entity.files ?files)
+        (set @entity.target @config.target)
+        (set @entity.status fetching)
+        (set @entity.createdAt (time/now))
+        (call-service "migration" "listDocuments" { connectionRef: @config.connectionRef, files: @entity.files, source: @entity.source }
+          { emit: { success: DOCUMENTS_LISTED, failure: MIGRATION_CALL_FAILED } })
+    }
+
+    state fetching {
+      DOCUMENTS_LISTED -> mapping
+        (set @entity.documents ?documents)
+        (set @entity.status mapping)
+        (emit MIGRATION_FETCHED { documents: @entity.documents })
+      ;; Self-loops so the validator sees in-atom listeners for the
+      ;; externally-consumed staging events.
+      MIGRATION_FETCHED -> mapping
+      MIGRATION_DOCUMENT -> mapping
+      MIGRATION_CALL_FAILED -> failed
+        (set @entity.error ?error)
+        (set @entity.status failed)
+        (persist create MigrationJob {
+          createdAt: @entity.createdAt
+          error: @entity.error
+          source: @entity.source
+          stats: @entity.stats
+          status: @entity.status
+          target: @entity.target
+        })
+        (emit MIGRATION_FAILED { error: @entity.error })
+    }
+
+    state mapping {
+      FETCH_DOCUMENT -> mapping
+        (call-service "migration" "fetchDocument" { connectionRef: @config.connectionRef, documentId: ?documentId, source: @entity.source }
+          { emit: { success: DOCUMENT_FETCHED, failure: MIGRATION_CALL_FAILED } })
+      DOCUMENT_FETCHED -> mapping
+        (set @entity.document ?document)
+        (emit MIGRATION_DOCUMENT { document: @entity.document })
+      MIGRATION_STAGED -> reviewing
+        (set @entity.stats ?stats)
+        (set @entity.status reviewing)
+        (emit MIGRATION_REVIEW_READY { stats: @entity.stats })
+      MIGRATION_DISCARDED -> idle
+        (set @entity.status idle)
+        (set @entity.documents [])
+        (set @entity.document {})
+        (set @entity.stats {})
+      MIGRATION_CALL_FAILED -> failed
+        (set @entity.error ?error)
+        (set @entity.status failed)
+        (persist create MigrationJob {
+          createdAt: @entity.createdAt
+          error: @entity.error
+          source: @entity.source
+          stats: @entity.stats
+          status: @entity.status
+          target: @entity.target
+        })
+        (emit MIGRATION_FAILED { error: @entity.error })
+    }
+
+    state reviewing {
+      MIGRATION_APPROVED -> committing
+        (set @entity.status committing)
+        (call-service "migration" "commit" { jobId: @entity.id, units: ?units }
+          { emit: { success: COMMITTED, failure: MIGRATION_CALL_FAILED } })
+      MIGRATION_REJECTED -> mapping
+        (set @entity.status mapping)
+      MIGRATION_REVIEW_READY -> reviewing
+      MIGRATION_DISCARDED -> idle
+        (set @entity.status idle)
+        (set @entity.documents [])
+        (set @entity.document {})
+        (set @entity.stats {})
+    }
+
+    state committing {
+      COMMITTED -> done
+        (set @entity.stats (object/merge @entity.stats { committed: ?committed, failed: ?failed }))
+        (set @entity.status done)
+        (persist create MigrationJob {
+          createdAt: @entity.createdAt
+          error: ""
+          source: @entity.source
+          stats: @entity.stats
+          status: @entity.status
+          target: @entity.target
+        })
+        (emit MIGRATION_COMPLETED { stats: @entity.stats })
+      MIGRATION_CALL_FAILED -> failed
+        (set @entity.error ?error)
+        (set @entity.status failed)
+        (persist create MigrationJob {
+          createdAt: @entity.createdAt
+          error: @entity.error
+          source: @entity.source
+          stats: @entity.stats
+          status: @entity.status
+          target: @entity.target
+        })
+        (emit MIGRATION_FAILED { error: @entity.error })
+    }
+
+    state done {
+      RESET -> idle
+        (set @entity.status idle)
+        (set @entity.error "")
+        (set @entity.documents [])
+        (set @entity.document {})
+        (set @entity.stats {})
+      ;; Self-loop so the validator sees an in-atom listener for the
+      ;; externally-consumed completion event.
+      MIGRATION_COMPLETED -> done
+    }
+
+    state failed {
+      MIGRATION_RETRY -> fetching
+        (set @entity.status fetching)
+        (set @entity.error "")
+        (call-service "migration" "listDocuments" { connectionRef: @config.connectionRef, files: @entity.files, source: @entity.source }
+          { emit: { success: DOCUMENTS_LISTED, failure: MIGRATION_CALL_FAILED } })
+      RESET -> idle
+        (set @entity.status idle)
+        (set @entity.error "")
+        (set @entity.documents [])
+        (set @entity.document {})
+        (set @entity.stats {})
+      ;; Mirrors the done self-loop: MIGRATION_FAILED is emitted for
+      ;; downstream consumers and listened to here for the validator.
+      MIGRATION_FAILED -> failed
+    }
+
+    emits {
+      DOCUMENTS_LISTED {
+        documents : [object]!
+      }
+        @description "migration.listDocuments service result, flattened onto the payload by the call-service effect executor"
+        @tier "secondary"
+      DOCUMENT_FETCHED {
+        document : object!
+      }
+        @description "migration.fetchDocument service result, flattened onto the payload by the call-service effect executor"
+        @tier "secondary"
+      COMMITTED {
+        committed : number!
+        failed : [object]!
+      }
+        @description "migration.commit service result — committed count plus per-unit failures"
+        @tier "secondary"
+      MIGRATION_CALL_FAILED {
+        error : string!
+      }
+        @description "migration service call failure signal — lands the run in failed, never a silent swallow"
+        @tier "secondary"
+      MIGRATION_FETCHED -> external {
+        documents : [object]!
+      }
+        @description "Source documents are listed and the run is ready for staging (deterministic pipeline or agent)"
+        @synonyms "import fetched, source listed, documents ready"
+        @tier "domain"
+      MIGRATION_DOCUMENT -> external {
+        document : object!
+      }
+        @description "A single fetched document's content, for the host staging layer to map into target units"
+        @synonyms "document loaded, content fetched"
+        @tier "domain"
+      MIGRATION_REVIEW_READY -> external {
+        stats : object!
+      }
+        @description "Staging is complete; the preview is ready for the approval gate"
+        @synonyms "preview ready, staging complete, review import"
+        @tier "domain"
+      MIGRATION_COMPLETED -> external {
+        stats : object!
+      }
+        @description "The commit drained through the host sink; stats carry committed and per-unit failed counts"
+        @synonyms "import done, migration complete, data imported"
+        @tier "domain"
+      MIGRATION_FAILED -> external {
+        error : string!
+      }
+        @description "The run failed; error carries the service-reported detail and the terminal job row was persisted"
+        @synonyms "import failed, migration error"
+        @tier "domain"
+    }
+
+    listens {
+      MIGRATION_START {
+        source : object!
+        files : [object]
+      }
+        @description "Starts an import run. source is the ImportSource descriptor; files carries client file metadata for upload sources. Also reached via a sibling std-import's IMPORT_REQUESTED."
+        @synonyms "start import, run migration, import data"
+        @tier "domain"
+      FETCH_DOCUMENT {
+        documentId : string!
+      }
+        @description "Fetch one document's full content from the source during staging"
+        @tier "internal"
+      MIGRATION_STAGED {
+        stats : object!
+      }
+        @description "Host staging finished — units are staged and validated; stats summarize staged/skipped counts for the preview"
+        @tier "internal"
+      MIGRATION_APPROVED {
+        units : [object]!
+      }
+        @description "The user approved the preview; units are the staged ImportUnits to commit through the host sink"
+        @synonyms "approve import, confirm migration"
+        @tier "domain"
+      MIGRATION_REJECTED
+        @description "The user sent the preview back for more staging"
+        @tier "internal"
+      MIGRATION_DISCARDED
+        @description "The run was discarded before commit"
+        @tier "internal"
+      MIGRATION_RETRY
+        @description "Re-runs the fetch after a failure, with the same source"
+        @tier "internal"
+      RESET
+        @description "Returns the job to idle from a terminal state"
+        @tier "internal"
+    }
+
+    config {
+      target : string = ""
+        @label "Target entity"
+        @description "Name of the host entity this import writes into (e.g. the organism's own entity). The migration service derives the full target descriptor from the running app's schema."
+        @synonyms "destination, import into, target type"
+        @tier "domain"
+      connectionRef : string = ""
+        @label "Connection reference"
+        @description "Secret-store / environment KEY holding the source credentials. The reference is stored; the secret itself never enters config, traces, or snapshots — the migration service resolves it at run time. (Typed `string` until the `secret` config-field type lands in the lolo language — tracked gap.)"
+        @synonyms "credential key, connection string reference, secret name"
+        @tier "internal"
+    }
+  }
+
+  page "/migration-job" as MigrationJobPage -> MigrationJobLifecycle
+}

package/behaviors/lolo/infra/atoms/std-mod-queue.lolo

@@ -24,7 +24,7 @@ orbital ModQueueItemOrbital {
     flagCount : number @description "The number of times this item has been flagged." @synonyms "flags, flag_count, count"
     status : "pending" | "approved" | "rejected" | "escalated" @description "Current state of the moderation item." @synonyms "state, condition, stage" = pending
     reviewedBy : string @description "The user who performed the review action." @synonyms "reviewer, reviewerId, assignedTo"
-    reviewedAt : string @description "Timestamp indicating when the item was last reviewed." @synonyms "review date, review time, last reviewed"
+    reviewedAt : datetime @description "Timestamp indicating when the item was last reviewed." @synonyms "review date, review time, last reviewed"
     notes : string @description "Free-text comments or observations related to the item." @synonyms "comment, remark, observation, details"
   }
 

package/behaviors/lolo/ml/atoms/std-data-collector.lolo

@@ -0,0 +1,56 @@
+app std-data-collector "1.0.0"
+"std-data-collector — pure buffer-accumulation atom, parameterized for any ML domain. Collects data points into a buffer and fires BUFFER_READY with the full accumulated buffer once it reaches config.bufferSize, then resets for the next cycle. No ML compute, no model call — state machine + array operators only. Use ahead of a training loop, a batch inference call, or any downstream rung that needs a fixed-size window of accumulated observations."
+orbital MlDataCollectorOrbital {
+
+  entity DataBuffer [runtime] {
+    buffer : [any] @description "Data points accumulated in the current cycle." = []
+    count : int @description "Number of points currently in the buffer." = 0
+    status : "idle" | "collecting" = idle
+  }
+
+  trait DataCollectorRun -> @rebindable DataBuffer [lifecycle, instance] {
+    initial: collecting
+
+    state collecting {
+      INIT -> collecting
+        (set @entity.buffer [])
+        (set @entity.count 0)
+        (set @entity.status idle)
+
+      COLLECT -> collecting
+        (let ((newBuffer (array/append @entity.buffer ?point))
+              (newCount (+ @entity.count 1)))
+          (if (>= @newCount @config.bufferSize)
+              (do
+                (set @entity.buffer [])
+                (set @entity.count 0)
+                (set @entity.status idle)
+                (emit BUFFER_READY { buffer: @newBuffer, count: @newCount }))
+              (do
+                (set @entity.buffer @newBuffer)
+                (set @entity.count @newCount)
+                (set @entity.status collecting))))
+    }
+
+    emits {
+      BUFFER_READY -> external { buffer : [any]!, count : int! }
+        @description "Fired when the buffer reaches config.bufferSize; carries the full accumulated buffer and its count, then the buffer resets for the next cycle."
+        @tier "primary"
+    }
+
+    listens {
+      COLLECT {
+        point : any!
+      }
+    }
+
+    config {
+      bufferSize : int = 100
+        @label "Buffer size"
+        @description "Number of data points collected before BUFFER_READY fires."
+        @tier "domain"
+    }
+  }
+
+  page "/ml-data-collector" as MlDataCollectorPage -> DataCollectorRun
+}

package/behaviors/lolo/ml/atoms/std-graph-builder.lolo

@@ -0,0 +1,90 @@
+app std-graph-builder "1.0.0"
+"Graph construction atom — builds node/edge structures from an entity collection for downstream GNN pipelines; pure array/object transform, no ML compute."
+
+orbital GraphBuilderOrbital {
+
+  entity GraphStructure [runtime] {
+    nodes     : [object] = []
+    edges     : [object] = []
+    nodeCount : int = 0
+    edgeCount : int = 0
+    status    : "idle" | "built" = idle
+  }
+
+  trait GraphBuilderRun -> GraphStructure [lifecycle, instance] {
+    initial: idle
+
+    config {
+      edgeField : string = ""
+        @label "Edge field"
+        @description "Field on each source entity holding its adjacency — an array of target ids"
+        @tier "domain"
+      nodeFeatures : [string] = []
+        @label "Node features"
+        @description "Entity fields carried onto each node alongside id"
+        @tier "domain"
+      directed : boolean = false
+        @label "Directed"
+        @description "Carried through for downstream consumers; edges are emitted once per adjacency entry, so an undirected reader should treat each edge as bidirectional"
+        @tier "policy"
+    }
+
+    state idle {
+      INIT -> idle
+        (set @entity.nodes [])
+        (set @entity.edges [])
+        (set @entity.nodeCount 0)
+        (set @entity.edgeCount 0)
+        (set @entity.status idle)
+
+      BUILD_GRAPH -> built
+        (let ((nodeFields (array/unique (array/append @config.nodeFeatures "id")))
+              (nodes (array/map ?entities (fn e (object/pick @e @nodeFields))))
+              (edges (array/flatten (array/map ?entities (fn e
+                        (array/map (object/get @e @config.edgeField [])
+                          (fn target { source: (object/get @e "id"), target: @target })))))))
+          (do
+            (set @entity.nodes @nodes)
+            (set @entity.edges @edges)
+            (set @entity.nodeCount (array/len @nodes))
+            (set @entity.edgeCount (array/len @edges))
+            (set @entity.status built)
+            (emit GRAPH_READY {
+              nodes: @nodes,
+              edges: @edges,
+              nodeCount: (array/len @nodes),
+              edgeCount: (array/len @edges)
+            })))
+    }
+
+    state built {
+      INIT -> built
+        (set @entity.status built)
+      RESET -> idle
+        (set @entity.nodes [])
+        (set @entity.edges [])
+        (set @entity.nodeCount 0)
+        (set @entity.edgeCount 0)
+        (set @entity.status idle)
+    }
+
+    emits {
+      GRAPH_READY -> external {
+        nodes : [object]!
+        edges : [object]!
+        nodeCount : int!
+        edgeCount : int!
+      }
+        @description "Fired when node/edge structures have been built from the source entity collection"
+        @tier "primary"
+    }
+
+    listens {
+      BUILD_GRAPH {
+        entities : [object]!
+      }
+    }
+  }
+
+  page "/graph-builder" as GraphBuilderPage -> GraphBuilderRun
+}

package/behaviors/lolo/ml/atoms/std-ml-similarity.lolo

@@ -74,21 +74,33 @@ orbital MlSimilarityOrbital {
     state embedding {
       EMBEDDED -> resolved
         (set @entity.embeddings ?result)
-        (set @entity.queryVector (array/first @entity.embeddings))
-        (set @entity.candidateVectors (array/drop @entity.embeddings 1))
         (set @entity.status resolved)
-        (let ((nearest (array/nearest @entity.queryVector @entity.candidateVectors)))
+        ;; An embed result without query + at least one candidate vector is an
+        ;; abstain, not a crash — the rung can prove nothing from it.
+        (if (< (array/len ?result) 2)
           (do
-            (set @entity.matchIndex (object/get @nearest "index"))
-            (set @entity.matchScore (object/get @nearest "score"))
-            (set @entity.matchMargin (object/get @nearest "margin"))
-            (if (and (>= @entity.matchScore @config.floor) (>= @entity.matchMargin @config.margin))
-                (do
-                  (set @entity.reason "")
-                  (emit SIMILARITY_MATCHED { index: @entity.matchIndex, score: @entity.matchScore }))
-                (do
-                  (set @entity.reason (if (< @entity.matchScore @config.floor) "below floor" "thin margin"))
-                  (emit SIMILARITY_ABSTAINED { reason: @entity.reason, request: @entity.request })))))
+            (set @entity.queryVector [])
+            (set @entity.candidateVectors [])
+            (set @entity.matchIndex 0)
+            (set @entity.matchScore 0)
+            (set @entity.matchMargin 0)
+            (set @entity.reason "embedding result incomplete")
+            (emit SIMILARITY_ABSTAINED { reason: "embedding result incomplete", request: @entity.request }))
+          (do
+            (set @entity.queryVector (array/first @entity.embeddings))
+            (set @entity.candidateVectors (array/drop @entity.embeddings 1))
+            (let ((nearest (array/nearest @entity.queryVector @entity.candidateVectors)))
+              (do
+                (set @entity.matchIndex (object/get @nearest "index"))
+                (set @entity.matchScore (object/get @nearest "score"))
+                (set @entity.matchMargin (object/get @nearest "margin"))
+                (if (and (>= @entity.matchScore @config.floor) (>= @entity.matchMargin @config.margin))
+                    (do
+                      (set @entity.reason "")
+                      (emit SIMILARITY_MATCHED { index: @entity.matchIndex, score: @entity.matchScore }))
+                    (do
+                      (set @entity.reason (if (< @entity.matchScore @config.floor) "below floor" "thin margin"))
+                      (emit SIMILARITY_ABSTAINED { reason: @entity.reason, request: @entity.request })))))))
 
       EMBED_FAILED -> resolved
         (set @entity.embeddings [])

package/behaviors/lolo/ml/atoms/std-tokenizer.lolo

@@ -0,0 +1,108 @@
+app std-tokenizer "1.0.0"
+"std-tokenizer — a text-preprocessing atom for tokenization. Splits raw text into a token sequence using a configurable method (whitespace, character, or arbitrary delimiter), normalizes and truncates the sequence, then maps each token to a vocabulary id (falling back to unkId when the token is absent from config.vocab). Feeds downstream embedding or sequence-model atoms. Pure circuit logic: str/* and array/* operators only, no ML compute, no model call."
+
+orbital MlTokenizerOrbital {
+
+  entity TokenSequence [runtime] {
+    text       : string  = ""
+    tokens     : [string] = []
+    tokenIds   : [int]    = []
+    tokenCount : int      = 0
+    request    : object   = {}
+    status     : "idle" | "checked" = idle
+  }
+
+  trait TokenizerRun -> TokenSequence [lifecycle, instance] {
+    initial: idle
+
+    config {
+      method : "whitespace" | "character" | "delimiter" = whitespace
+        @label "Method"
+        @description "Whitespace splits on single spaces, character splits into individual characters, delimiter splits on config.delimiter"
+        @tier "policy"
+      delimiter : string = ","
+        @label "Delimiter"
+        @description "Split delimiter used when method is delimiter; ignored otherwise"
+        @tier "domain"
+      lowercase : boolean = true
+        @label "Lowercase"
+        @description "Lowercase every token before vocabulary lookup"
+        @tier "policy"
+      trimWhitespace : boolean = true
+        @label "Trim whitespace"
+        @description "Trim each token and drop tokens that are empty afterward"
+        @tier "policy"
+      maxLength : int = 512
+        @label "Max length"
+        @description "Truncate the token sequence to at most this many tokens"
+        @tier "policy"
+      vocab : Map string int = {}
+        @label "Vocabulary"
+        @description "Token-to-id map; a token absent from this map resolves to unkId"
+        @tier "domain"
+      unkId : int = 0
+        @label "Unknown token id"
+        @description "Id assigned to a token that is not present in config.vocab"
+        @tier "policy"
+    }
+
+    state idle {
+      INIT -> idle
+        (set @entity.text "")
+        (set @entity.tokens [])
+        (set @entity.tokenIds [])
+        (set @entity.tokenCount 0)
+        (set @entity.request {})
+        (set @entity.status idle)
+
+      TOKENIZE -> checked
+        (let ((split (if (== @config.method "character")
+                        (str/split ?text "")
+                        (str/split ?text (if (== @config.method "delimiter") @config.delimiter " "))))
+              (trimmed (if @config.trimWhitespace (array/map @split (fn t (str/trim @t))) @split))
+              (normalized (if @config.lowercase (array/map @trimmed (fn t (str/lower @t))) @trimmed))
+              (nonEmpty (array/filter @normalized (fn t (> (str/len @t) 0))))
+              (truncated (array/slice @nonEmpty 0 @config.maxLength))
+              (ids (array/map @truncated (fn t (object/get @config.vocab @t @config.unkId)))))
+          (do
+            (set @entity.text ?text)
+            (set @entity.tokens @truncated)
+            (set @entity.tokenIds @ids)
+            (set @entity.tokenCount (array/len @truncated))
+            (set @entity.request ?request)
+            (set @entity.status checked)
+            (emit TOKENIZED { tokens: @entity.tokens, tokenIds: @entity.tokenIds, tokenCount: @entity.tokenCount })))
+    }
+
+    state checked {
+      INIT -> checked
+        (set @entity.status checked)
+      RESET -> idle
+        (set @entity.text "")
+        (set @entity.tokens [])
+        (set @entity.tokenIds [])
+        (set @entity.tokenCount 0)
+        (set @entity.request {})
+        (set @entity.status idle)
+    }
+
+    emits {
+      TOKENIZED -> external {
+        tokens : [string]!
+        tokenIds : [int]!
+        tokenCount : int!
+      }
+        @description "Text tokenized into a normalized, truncated token sequence with vocabulary ids"
+        @tier "primary"
+    }
+
+    listens {
+      TOKENIZE {
+        text : string!
+        request : object
+      }
+    }
+  }
+
+  page "/ml-tokenizer" as MlTokenizerPage -> TokenizerRun
+}