Operating Modes
Ce contenu n’est pas encore disponible dans votre langue.
Where things live. Where
makehappens. How the AFS, KLS, and OPS flow between actors.
The same product runs in five different topologies. What varies is where each store lives and who runs the build. The code paths converge.
The Three Stores
Section titled “The Three Stores”- AFS — the analytical framework. Git repo. All YAML, SQL, contracts, dbt models. Authored by people;
makeadds the extracted inputs and the build log. - KLS — the knowledge store. DuckDB file. Built from the AFS by
make. Read-only once built. - OPS — the operational store. A per-tenant SQLite/WAL file, or a Cloudflare D1 in the always-on cloud modes. Notes, bookmarks, bell resolutions, selectors, desks, preferences. Mutable, and it lives next to the user.
The OPS has no arrow into the AFS. It is a side store JinDesk reads and writes — never a feedback path into the build. It outlives every KLS and is never rebuilt: restore it from a backup rather than regenerating it.
One Build Command
Section titled “One Build Command”make is the single build entrypoint. It gathers its inputs, commits them to git, and only then builds the KLS — in that order, with every side effect on the far side of the commit.
Why the AFS is the build input
Section titled “Why the AFS is the build input”make is the security boundary. Whoever controls make controls the analytical truth. The input phases run inside make but commit their outputs to the AFS before the build reads them, which means:
- Every build is reproducible from the AFS commit it was built on.
- Everything that went into the build is in git — auditable, reversible.
- The build portion of
makeconsumes only the AFS, nothing else. No network calls, no OPS access.
The AFS commit produced at the end of each build captures the whole run in its history.
Inspection
Section titled “Inspection”jin inspect # read-only view of the extraction surfacejin inspect --contract # full pipeline.yml contract (purpose, source, output, expected)jin inspect --check # verify SHA-256 hashes without running extractioninspect never runs extraction — for that, use jin make.
The Five Modes
Section titled “The Five Modes”Mode 1 — Local
Section titled “Mode 1 — Local”Everything on one machine. The developer’s laptop.
- Who runs make: the developer, on the same machine
- Auth: none (god mode). Git identity from local git config
- Git: local. Push the AFS to a remote when ready — or never
Mode 2 — Proxy (P2P2P)
Section titled “Mode 2 — Proxy (P2P2P)”KLS and OPS on the data owner’s machine. JinDesk in the cloud, reaching both through the tunnel.
- Who runs make: the data owner, locally
- Auth: stealth (none) or an identified session
- Git: the owner pushes the AFS; remote viewers never touch git
- One OPS — on the owner’s machine. Everyone reads and writes the same OPS through the tunnel; the cloud stores nothing. Your data, your machine extends to operational state too
This is the primary mode for sensitive data. See the P2P2P concept page.
Mode 3 — Cloud (R2)
Section titled “Mode 3 — Cloud (R2)”KLS uploaded to R2. JinDesk and the OPS (a D1 per tenant) in the cloud.
- Who runs make: the developer, locally. Then
jin shipbuilds, uploads the KLS, and refreshes the running instances — orjin syncconverges everything, both directions - Auth: required for all cloud users
- The refresh matters: uploading to R2 changes nothing by itself. A running instance is still serving the KLS it downloaded on boot, so publishing ends with a per-tenant, ETag-conditional refresh — only the tenants that actually changed are swapped
- OPS — one D1 per tenant. The strongest isolation available: a cross-tenant query is impossible, not merely discouraged
- Why: always-on, low-latency, shareable by URL. The trade-off: the KLS leaves the site
Mode 4 — Semi-Cloud
Section titled “Mode 4 — Semi-Cloud”KLS built locally and stays. The OPS follows it home. No KLS upload.
- Who runs make: the owner, locally
- Why: compliance — the analytical data can’t leave the site
- The OPS follows the KLS (local by default), reached through the tunnel as in Mode 2. It may live in the cloud as a D1 only where policy allows
- Auth: required for cloud users
The difference from Mode 2 is intent, not wiring: Mode 2 chooses local because the data is sensitive; Mode 4 is required to by policy.
Mode 5 — Make-as-a-Service
Section titled “Mode 5 — Make-as-a-Service”
makeruns in the cloud. No local machine needed.
- Who runs make: a cloud worker — a long-lived daemon on a cloud machine, or a one-shot container
- It is the same
make. The worker does not reimplement the build; it shells out tojin makeand streams that run’s events back as they happen, so a cloud build is subject to exactly the same input/build split as a laptop one - Trigger: a run request to the worker, a schedule, or a push
- Buckets instead of a working copy: the runner can pull and push every store — the AFS included — from object storage, so this topology needs no git remote at all
- Auth: a bearer token on every worker endpoint but the liveness check
A deployed server is not a read-only consumer of R2 — it can build. Mode 3 describes the common topology today, not a limit on what a server is.
The OPS — Messenger and Memory
Section titled “The OPS — Messenger and Memory”The OPS serves two roles. All of it stays in the OPS.
| Role | Content | Retention |
|---|---|---|
| Memory | Notes, bookmarks | Long-term |
| Memory | Bell resolutions, selectors, desks | Long-term |
| Memory | Acknowledgments, roster, preferences | Long-term |
| Messenger | Recents (navigation journal) | Short-term, rotated |
| Messenger | Session state (current filters, scroll) | Session-only |
Authored notes still reach the KLS, by a separate path: they are written as AFS YAML and baked at build time. That is authoring. A note created in JinDesk stays in the OPS.
One OPS per tenant. Not local plus cloud — one instance, one truth. Where it lives is a deployment decision:
| Mode | OPS lives… | Reached by… |
|---|---|---|
| Local | The developer’s machine | JinDesk on localhost |
| Proxy / Semi-Cloud | The owner’s machine — the cloud is only a tunnel | JinDesk through the proxy |
| Cloud / Make-as-a-Service | The cloud — one D1 per tenant | JinDesk directly |
Nobody needs git to use JinDesk. Git is the AFS’s transport and provenance layer, not the runtime: it carries the framework between machines and records what each build was made from. Notes, bookmarks and selectors never go near it.
Decision Matrix
Section titled “Decision Matrix”| Factor | Local | Proxy | Cloud | Semi-Cloud | Make-as-Service |
|---|---|---|---|---|---|
| KLS location | Local | Local | Cloud (R2) | Local | Cloud (R2) |
| OPS location | Local | Local (via tunnel) | Cloud (D1) | Local (via tunnel) | Cloud (D1) |
| Who runs make | Developer | Owner | Developer | Owner | Cloud worker |
| Operational compliance | Best | Best | KLS in cloud | KLS local | Full cloud |
| Collaboration | Single user | Multi-user (session) | Multi-user (always on) | Multi-user | Multi-user |
| Internet required | No | Yes | Yes | Yes | Yes |
| Git knowledge needed | Author only | Author only | Author only | Author only | Author only |
| Setup complexity | Trivial | One command | R2 credentials | Proxy + policy call | Worker + credentials |
| Viewer login | — | Optional (stealth) | Required | Required | Required |
Recommendation: start with Local (Mode 1) and Proxy (Mode 2) for sensitive data. Move to Cloud (Mode 3) for non-sensitive. Make-as-a-Service (Mode 5) is the shape for scale.
The Cut
Section titled “The Cut”The cut inside make — between gathering the inputs and building from them — is the security boundary, and it is drawn across a git commit.
- The input phases have side effects: they pull from source systems, write into the AFS, and commit.
- The build phases have none: they read the AFS and write the KLS. That’s it. No network calls, no OPS access.
Everything that feeds a build is in git — auditable, reproducible, reversible. The OPS is the collaboration layer: it doesn’t need git, it doesn’t need make, it’s where people work. Everything else is infrastructure.
Related
Section titled “Related”- Pipeline Overview — the layer-by-layer transformation
- Deploy Guide — how to stand each mode up in practice
- P2P2P concept — deep dive on Mode 2
- Make guide — day-to-day usage