Enforcing Taubyte Constraints

Enforcing Taubyte Constraints

When to use

• Final review pass before tau push / git push
• Auditing a session's actions ("did I cover all the hard rules?")
• Reviewing a teammate's PR against a Taubyte project
• Onboarding a new agent / engineer to the project

How to use this skill

Each rule is a one-liner. The link points to the skill that explains and enforces the rule. Read the rule list top-to-bottom; if any rule is unclear or violated, jump to the linked skill before continuing.

Architecture & sources of truth

1. GitHub is the single source of truth. Clouds (remote and Dream) build and serve from what's pushed; never bypass git. → understanding-taubyte-architecture
2. Config repo is tau-managed. Don't hand-edit config/... YAML; mutations go through tau new / tau edit / tau delete. → editing-taubyte-resources
3. Domains are CLI-managed always. Never vim config/domains/<x>.yaml; use tau new domain / tau edit domain / tau delete domain. → creating-taubyte-resources

Naming & validation

4. Project name = snake_case. Dashes break tau validate config with invalid variable name. → bootstrapping-taubyte-projects
5. config/config.yaml must have a real notification.email. Empty values fail config-compile with mail: no address. → bootstrapping-taubyte-projects
6. Forbidden flag: never pass --generated-fqdn-prefix / --g-prefix to tau new domain. Use --generated-fqdn alone or --fqdn <controlled>. → creating-taubyte-resources
7. Database --min < --max. --min 1 --max 1 fails. → creating-taubyte-resources
8. One function per (path, method). Never comma-separated methods; split into separate function resources. → authoring-taubyte-function-types

Context hygiene

9. Verify tau --json current before any mutation (push, delete, inject, tau new resource). The Project field must equal the on-disk project. → selecting-taubyte-context
10. After tau new project, immediately re-run tau select project --name <same> then verify. Selection drift after new project is the usual cause of "wrong project" pushes. → bootstrapping-taubyte-projects
11. Clear application after app-scoped work: tau clear application before returning to project-level resources. → selecting-taubyte-context

Code authoring rules

12. Function root layout (Go): empty.go and go.mod at the function root. Never create a lib/ subdirectory; never hand-author main.go. Corollary: careless tau build can still generate those paths as root-owned junk — never commit them; delete, git rm --cached, and .gitignore before push. → writing-taubyte-functions, verifying-taubyte-functions
13. Package name is NOT main. Use lib (or any other name). → writing-taubyte-functions
14. //export <name> must equal execution.call in the function YAML. → authoring-taubyte-function-types
15. HTTP handler order: Headers().Set → Write(body) → Return(status), in that order. Returning before writing yields empty/broken responses. → writing-taubyte-functions
16. YAML matcher ↔ Go literal must match exactly, including any leading /:
    • databases/<x>.yaml match ↔ database.New("<match>")
    • storages/<x>.yaml match ↔ storage.New("<match>")
    • messaging/<x>.yaml channel.match ↔ function trigger.channel ↔ pubsubnode.Channel("<match>") → writing-taubyte-functions

Build & runtime config

17. Env vars live in .taubyte/build.sh only as export NAME=value, never in .taubyte/config.yaml. → configuring-taubyte-build-runtime
18. Websites must write to /out. Use the stack's real output directory; don't assume Vite (dist/) on a CRA repo (build/). → building-taubyte-websites
19. .taubyte/build.sh must be non-empty and executable. Empty scripts "build successfully" while producing nothing. → configuring-taubyte-build-runtime

Push & build triggers

20. --message is required when --defaults is set. Every tau push invocation in non-interactive mode must include -m "<msg>". → pushing-taubyte-projects
21. Push order: project config first → wait for config build success → then code/website/library. → pushing-taubyte-projects
22. Don't bypass a failing tau push project with raw git push for the project's config/code repos. Website/library repos may use raw git as a fallback when tau push website|library is unavailable. → pushing-taubyte-projects

Dream-local rules

23. First-run bootstrap: dream inject push-all once on a fresh project before push-specific becomes reliable. → triggering-dream-builds
24. push-specific requires long flags + universe last to avoid Required flags "repository-id, repository-fullname" not set. → triggering-dream-builds
25. Register website/library repos with the local repository service after tau import website|library (PUT /repository/github/<repo_id>); otherwise push-specific won't trigger builds for them. → registering-dream-repositories
26. dream inject is Dream-only. Never run it against a remote cloud — webhooks handle that side. → deploying-to-remote-clouds 26.1. Dream requires a real git HEAD in each injected repo. Empty-branch repos (no commits) can make inject fail with getting HEAD ... reference not found. → triggering-dream-builds

Remote-cloud rules

27. Project-id alignment: config/config.yaml id: must equal the cloud's canonical project id, or every push fails with project ids not equal. → deploying-to-remote-clouds
28. Generate domains only while Cloud Type: remote (or the right Dream universe). The generated TLD is per-cloud. → deploying-to-remote-clouds
29. Use --type https (not http) for remote functions. Remote gateways expect TLS. → authoring-taubyte-function-types
30. Remote website/library builds require registration + clean hooks. If remote builds are silent: tau import website|library <name> on that cloud, ensure a single GitHub webhook (dedupe if needed), then push a commit and verify via job logs. → deploying-to-remote-clouds, pushing-taubyte-projects

Platform / shell

31. Git Bash on Windows: prefix path-like flags with MSYS_NO_PATHCONV=1 to avoid path mangling on --paths, --protocol, etc. → creating-taubyte-resources
32. Inline function disk path must match the active builder. An extra applications/ segment (or the inverse) makes builds fail with .taubyte not found under the path the job reports. Align code/.../functions/<fn>/ to that path before changing anything else. → creating-taubyte-resources
33. PUT may not route like GET/DELETE even when YAML declares PUT — the edge can return no HTTP match for method PUT while other methods work; logs may be incomplete. Prefer a dedicated POST route (e.g. /api/resource/update) as a separate function until routing is confirmed. → authoring-taubyte-function-types
34. Keep scaffold empty.go (and matching FILENAME in build.sh) unless you have an image-verified recipe — renaming to lib.go / changing the entry file without full alignment breaks TinyGo and can drop artifact.wasm. → configuring-taubyte-build-runtime, writing-taubyte-functions
35. Website .taubyte/build.sh is executable shell only — never paste HTML or other markup into it. A merged file breaks the script; replace with a minimal mkdir -p /out + copy pattern. → building-taubyte-websites
36. Remote / public cloud: never ship *.default.localtau FQDNs — the config compiler uses public DNS (1.1.1.1-class); Dream hostnames fail TXT checks. Delete + recreate domains via tau with a remote-suitable --fqdn. → deploying-to-remote-clouds, editing-taubyte-resources
37. Remote: GET / broken but /api/... OK means the website repo artifact is missing — tau push website <site> + verify AssetCid on that repo’s build job, not further function debugging by default. → pushing-taubyte-projects, deploying-to-remote-clouds, building-taubyte-websites
38. tau pull → already up-to-date + non-zero exit is often a CLI quirk — confirm with git fetch/git status before treating it as failure. → pushing-taubyte-projects
39. Sibling dirs (tau_notes vs tau_it) + global tau selection: tau --json current → Project must equal the config/config.yaml name: in the tree you cd’d into. → selecting-taubyte-context

Pre-push checklist (copy into the session)

Pre-push audit:
- [ ] tau --json current shows expected Cloud + Cloud Type + Project (rule 9)
- [ ] No raw YAML edits in config/ this session (rules 2, 3)
- [ ] Project name + matchers + channels are snake_case where required (rules 4, 16)
- [ ] If Go function: empty.go at root, package != main, //export matches call (rules 12, 13, 14)
- [ ] HTTP handlers: headers -> write -> Return(status) (rule 15)
- [ ] Env vars only in .taubyte/build.sh (rule 17); /out for websites (rule 18)
- [ ] tau push has -m "<message>" (rule 20)
- [ ] Push order: config first, then code/website/library (rule 21)
- [ ] Dream: bootstrap with push-all done, push-specific uses long flags + universe last (rules 23, 24)
- [ ] Remote: id alignment OK, no dream inject (rules 26, 27)
- [ ] If remote/Dream complained about `.taubyte` path: function dir matches log (rule 32); website build.sh is pure shell (rule 35)
- [ ] Remote: no lingering `localtau` domains in config when target is public FQDN (rule 36); if static page 500: website build + AssetCid verified (rule 37); `tau pull` quirks checked with git (rule 38); `tau` Project matches directory `config.yaml name` (rule 39)

Related skills

• understanding-taubyte-architecture — why these rules exist
• troubleshooting-taubyte-issues (if added later) — what to do when one is violated
• The skill linked next to each rule above is the canonical owner for the rule's deep coverage