Files

T

alexei.dolgolyov 279f373f80 docs(extra_json): policy doc for containers.extra_json evolution

New CODEMAPS/container-extra-json.md documents the contract every
source plugin must follow when reading or writing containers.extra_json.
Closes the open architectural question that was tracked in
WORKLOAD_REFACTOR_TODO.md.

Covers:
- Schema position (column default, four write-path normalization
  sites) and ownership model (per-source row keys, current writers).
- Reader rules: tolerate unknown keys via default json.Unmarshal,
  tolerate decode failure where first-class columns suffice.
- Writer patterns: wholesale-overwrite (image source, single-writer
  short-lived rows) vs preserve-unknown-keys (static source, RMW with
  generic-map round-trip). Preserve-unknown-keys is the recommended
  default for new sources.
- Concurrency: SetMaxOpenConns(1) + WAL gives atomic per-row writes
  and consistent reader snapshots, but does NOT serialize multi-
  goroutine RMW — a per-workload sync.Mutex is required for that
  (fenced by TestSaveState_ConcurrentWritesDoNotLoseUpdates).
- What extra_json is NOT for (workload config, cross-source state,
  queryable data, secrets) and a checklist for adding a new field.
- Pointers to every example in tree: image's containerExtra writer/
  reader, static's saveState round-trip, workload_runtime.go's
  decode-and-tolerate consumer.

WORKLOAD_REFACTOR_TODO Container.extra_json question flipped to DONE.
CODEMAPS/INDEX bumped + entry linked.

Reviewer pass (code-reviewer subagent) caught one HIGH factual error
(wrong cross-source consumer claim) and several MEDIUM/LOW drifts;
all addressed inline before commit.

2026-05-16 22:00:41 +03:00

2.9 KiB

Raw Blame History

Tinyforge Codemaps — Index

Last Updated: 2026-05-16 (added container-extra-json policy doc)

This directory contains architectural maps of key Tinyforge subsystems. Each codemap focuses on one major area: core data types, contract surfaces, integration points, and recipes for extending the system.

Codemaps

Workload Plugin — Source × Trigger plugin contracts; registry lookups; webhook fan-out; how to add new kinds.
Discovery & Runtime API — /api/discovery/* helpers (Git provider probe, repo/branch/tree pickers, image conflicts); /api/workloads/{id}/runtime-state + /storage + /stop + /start; SSRF-safe HTTP client in internal/staticsite.
containers.extra_json Evolution Policy — Ownership model, reader/writer rules, wholesale-overwrite vs preserve-unknown-keys patterns, concurrency invariants; checklist for adding a new field without breaking older deployers.

Cross-References

Workload Refactor Handoff — docs/WORKLOAD_REFACTOR_TODO.md — Full status of the trigger-split, legacy cutover, and remaining Priority items
Webhook Documentation — docs/webhooks.md — Outgoing webhook events, signature scheme, receiver code samples
Observability + Event Triggers — docs/LOGSCAN_AND_TRIGGERS_TODO.md — Log scanning rules, event triggers, related infrastructure

How to Use These Codemaps

Starting a new feature in an existing area? Read the relevant codemap first to understand the contract surface and integration seams.
Adding a new plugin kind (Source or Trigger)? See the recipes in workload-plugin.md — "How to Add a New Source Kind" / "How to Add a New Trigger Kind".
Debugging a plugin dispatch failure (deploy, webhook, reconcile)? The "Data Flow" and "Integration Points" sections map out each path end-to-end.
Reviewing someone else's plugin PR? Check the contracts (Source.Deploy(), Trigger.Match(), etc.) against the descriptions here.

Coverage

These codemaps are automatically generated from the codebase structure. If a key file or area is missing, it indicates:

The area is under active refactor (see WORKLOAD_REFACTOR_TODO.md for priority order)
The area is legacy code scheduled for deprecation
The area is simple enough to document inline (JSDoc + comments in the source)

Freshness

Codemaps are updated whenever:

A new plugin kind is added
The contract surface changes (new Source/Trigger method, new Deps field, etc.)
Integration points shift (new API endpoint, new reconciler behavior, etc.)
A major refactor lands (see workload-refactor status for examples)

When you land a change that affects these areas, please update the relevant codemap and the Last Updated timestamp.

2.9 KiB Raw Blame History Unescape Escape