moby-core

moby-core defines the shared TypeScript contracts for MOBY-compatible cannabis operations tools. It gives independent modules a common vocabulary for run manifests, artifacts, warnings, input sources, summaries, domain objects, audit events, and workflow gates. The goal is simple: separate tools can produce outputs that are understandable across the MOBY ecosystem without sharing business logic.

Why this exists

Cannabis operators often work with messy POS exports, invoice data, shift notes, approval trails, and audit artifacts. If every tool invents its own schema, the handoff between modules, reviewers, and dashboards becomes fragile. moby-core gives those tools a shared contract language so outputs can be reviewed, displayed, and connected more consistently.

Ecosystem flow

Raw operator data
  -> module run
  -> normal artifact outputs
  -> moby-run-manifest.json
  -> TrackingTHC / downstream review tools

What this repo is

moby-core is a TypeScript contract package for operator-first cannabis workflows. It defines shared vocabulary and domain model definitions for manifests, artifacts, warnings, sources, summaries, audit events, and workflow gates.

This repo is the compatibility foundation between independent modules. Modules import these types so their outputs can be understood by other MOBY tools while each module keeps its own behavior and business logic.

What this repo is not

moby-core is not:

• a frontend app
• a CLI runtime
• an ERP
• a POS connector
• a compliance sync engine
• a dashboard
• a storage layer
• a JSON runtime validator
• a place for module business logic

Business logic, file-writing behavior, integrations, and runtime validation belong in module repos or consuming applications. moby-core only defines shared contracts.

Compatible modules

Current MOBY-compatible modules:

• trackingthc-import-mapper
• invoice-cost-spreader
• cannabis-approval-router
• cannabis-shift-handoff

Core concepts

• Run manifest: the ecosystem handoff file for a completed module run, usually written as moby-run-manifest.json.
• Artifact: a normal output file produced by a module for review, import, audit, or downstream display.
• Warning: an explicit issue, assumption, or review note produced during a run instead of being silently cleaned up.
• Source: the input data, file, system, or operator-provided context used by a module.
• Summary: high-level run metadata that helps reviewers understand status, counts, outcomes, or next steps.
• Domain object: a typed business entity shared across MOBY-compatible tools.
• Audit event: a typed record of what happened, who or what did it, where it came from, and what changed.
• Workflow gate: a contract for review, approval, handoff, or follow-up steps in an operator workflow.

Run manifests

moby-run-manifest.json records what ran, where the inputs came from, which artifacts were produced, which warnings occurred, and the summary/status metadata needed by viewers or downstream review tools.

Modules should keep their normal result artifacts and also write a moby-run-manifest.json when run in MOBY output mode. The manifest points at artifacts; it does not replace them.

Compatible module pattern

Compatible modules should:

• preserve their existing behavior
• optionally support a run directory or MOBY output mode
• write their normal result files
• write moby-run-manifest.json beside those outputs
• keep business logic inside the module repo
• use moby-core only for shared contracts

This pattern lets modules such as trackingthc-import-mapper, invoice-cost-spreader, cannabis-approval-router, and cannabis-shift-handoff stay small and focused while still producing reviewable outputs for the wider MOBY ecosystem.

TrackingTHC relationship

TrackingTHC consumes committed sample outputs from compatible modules:

• /moby-runs displays sample moby-run-manifest.json files in MOBY Mission Control.
• /import-review displays moby-import.json sidecars.

TrackingTHC acts as a viewer and review surface for MOBY-compatible outputs. It can display committed sample artifacts and manifests without owning the module logic that produced them.

Design principles

• Small tools over monoliths
• Reviewable artifacts over black-box automation
• Explicit warnings over silent cleanup
• Stable contracts over one-off schemas
• Operator-first workflows
• Audit trails by default

Core principle

Every important business action should answer:

1. What happened?
2. Who or what did it?
3. When did it happen?
4. What system did it come from?
5. What changed?
6. What needs to happen next?

Status

moby-core is an early portfolio/demo ecosystem contract package. APIs and contracts may evolve while the MOBY ecosystem is being shaped.