Super Factory Manager (SFM)

The project is developing a framework for snapshot episodes, action traces, and deterministic environments. The goal is to provide a system where game states and agent actions can be losslessly represented, replayed, and inspected.

Key capabilities being implemented include:

• Lossless Snapshots: Using a single canonical JSON file to represent complete snapshots and episodes (including frame t=0 and final-frame aliases).
• Deterministic Replay: A stateful keybinding engine that replays actions deterministically from recorded events and binding revisions.
• History and Versioning: An immutable branch history that distinguishes exact replays from semantic rebases, ensuring historical insertions do not change existing revisions.
• Inspection Tools: An in-game Episode Inspector for scrubbing files, events, actions, and environment state, and a History Graph panel for visualizing actions and non-linear descendants.
• Planning and Supervision: A bounded deterministic planner for reproducible routes and a supervision contract that separates goal predicates, hard invariants, and human approval.

The SFM client log console is designed to provide a unified, correlated observation view of logs from multiple runtimes (Java/Forge and Rust) and sources (SFM-authored logs, generic Log4j, and process-stdio).

Key Behaviors

• Automatic Integration: Existing SFM.LOGGER calls appear in the console automatically without manual palette appending.
• Unified Sink: Palette command responses are published through SFMClientLogSink and are visible in the same log-record view as standard logs.
• Correlated Views: Java Log4j/translatable logs and Rust tracing records share a single versioned, correlated view. While they do not claim wall-clock total ordering, they allow for cross-runtime observation.
• Source Provenance: SFM-authored Java records preserve the true application caller (class/method/file/line) in NDJSON format. When a matching generated manifest exists, it includes canonical URIs, columns, exact spans, and source hashes.
• Localization: SFM-authored semantic records include a stable message ID, localization key, English fallback, and typed/bounded arguments. The system supports English, localized, and bilingual projections.
• Workflow: The standard workflow for generating a combined artifact is: run client --branch 1.19.2 --log-file abc.ndjson This produces a parseable file containing Rust, Java SFM, generic Log4j, and process-stdio records.

Constraints and Non-Goals

• No Global Interference: The system does not replace Minecraft/Forge's global log viewer or change Log4j configuration for unrelated mods.
• No Forced Stack Walking: The default release profile does not force stack walking for unrelated Minecraft, Forge, or third-party-mod events to minimize performance overhead.
• No Third-Party Translation: The system does not attempt to translate third-party Minecraft/Forge/mod messages or infer localization keys from arbitrary English text.
• No Unbounded History: The system does not persist unbounded history or upload logs without an explicit network contract.

The Release Review Exploratory Usability plan is a framework designed to validate the usability of the Super Factory Manager (SFM) review loop. The goal is to ensure a discoverable, ordinary review process where users can find changes, compare them, attach concerns, and inspect comments without relying on memorized commands.

Key Usability Goals:

• Discoverability: Users should be able to find the next step in a review loop naturally.
• Traceability: Notifications and paths must be concise but provide exact traceability (e.g., via right-click options like open-path-as-text or open-path-in-explorer).
• Ergonomics: Support for both mouse-first and keyboard-first discovery, including cancellation, backtracking, and switching tasks during loading.
• Safety: Minecraft components should support clickable phrases with context actions, but must never execute arbitrary embedded commands from path contents.

Validation Environment:

• Primary validation is performed on Minecraft 1.19.2.

The extension enhances the development experience for SFM code with the following capabilities:

• Syntax highlighting: Provides color coding for SFM code based on your current VSCode theme.
• Tooltips: Hover over keywords to see brief descriptions and usage examples.
• Snippets: Accelerate coding with predefined snippets for: basic, energy, input, output, if, ifelse, ifelseif, and every.
• Folding: Allows collapsing code structures such as if or every blocks.
• Error checking & Warnings: Validates files upon saving to detect errors. It also provides warnings for mismatched inputs/outputs (e.g., an input with no corresponding output).
• Activity Bar: Accessible when a workspace folder is open and an .sfm or .sfml file is active. It provides access to examples (in-game and GitHub) and allows sharing work via external GitHub URLs or local folders.
• Markdown Support: Provides most extension effects (highlighting, tooltips, etc.) within .md files, though snippets are not supported in Markdown.

The Vox Terminal Bridge and Graceful Degradation Plan outlines the concurrent development tracks for improving terminal performance, rendering, and data propagation between the Rust-based teamy-terminal and the Java-based Super Factory Manager (SFM).

Key architectural shifts include:

• Decoupling: The Rust terminal implementation is moving from being a dependency of Teamy Studio to a standalone public MPL-2.0 repository: TeamDman/teamy-terminal.
• Parallel Tracks: Development is organized into tracks (S0 through S6) covering telemetry, CPU/GPU resource management, Rust push producers, slug correctness, Vulkan runtimes, and Java font/renderer implementations.
• Integration Ownership: To prevent conflicts, a single integration owner must control contract changes, generated Vox outputs, the SFM lock, and canonical plan updates. Agents and subagents must not concurrently edit canonical plans or generated Vox outputs.
• Integration Gates: The V-4.2c live normal/GUI-scale-7 matrix serves as a join gate, requiring runs from canonical 1.19.2 after immutable imports.

The Contextual Input Actions and Addressable Explorer plan defines the functional boundaries for SFM's interactive workspace and navigation systems.

In Scope

• Workspace & UI: SFM-owned full screens, workspace panels, and panel children. Includes support for Minecraft 1.19.2, narration, keyboard, mouse, and controller-compatible activation.
• Input & Bindings: Contextual dynamic bindings, command-draft completion, conflict reporting, and action discovery.
• Explorer & Addressing: Typed addresses, resolver/device registries, and explorer projections over actions, bindings, situations, and registries. Includes selection-backed session-scoped multi-root explorer locations.
• Text Editor (v3): File-backed documents with durable addresses, safe read-only opening, open/focus-at-range, and source-hash-aware snapshots.
• Code Intelligence: Location-aware Java definition lookup (JDK, dependency, project, member, local, annotation, and import symbols) and reference lookup. Includes Ctrl+hover/click, Alt+F7, right-click, and Alt+Enter parity.
• Syntax Highlighting: A versioned, Rust-owned Arborium syntax-highlighting service, initially supporting .java documents.

Out of Scope

• Modifying Microsoft Terminal or copying browser tab semantics (e.g., Ctrl+W).
• Global input grabbing that shadows Minecraft or other mods outside SFM contexts.
• Arbitrary host-filesystem access via sfm:path or enumerating ambient roots (home/drive) without a contextual seed.
• Implementing a general shell/pipeline language or arbitrary process execution.
• Enabling Arborium grammars beyond Java (follow-ups include Rust, JSON, Gradle/Groovy, PowerShell, Markdown, TypeScript, and TOML).
• Writable host-file editing, semantic diagnostics, or replacing the existing Java symbol engine with Arborium highlighting captures.

The project is transitioning from a provisional boolean review ledger to a general comment system. This system acts as a shared substrate where various types of data—such as human reviews, human approvals, audit findings, compiler diagnostics, diff presentations, and arbitrary notes—are treated as conventions on top of a common model rather than separate, incompatible data models.

Key Characteristics:

• Scope: Selection rules can identify glyphs across files, revisions, repositories, and Minecraft-version worktrees.
• Primary Use Case: An in-game source-review workspace.
• Extensibility: The model is designed to be usable by Rust CLI producers, Java compiler/audit adapters, future Vox clients, and exported review artifacts.
• Presentation: Source code is always presented as source code. ASTs and symbol indexes are used to assist in selecting and migrating source regions, but a generic tree viewer is not the primary experience.

In SFM (Super Factory Manager), redstone can be managed via mutable buffer storage. This allows for a buffer to store a specific redstone:: quantity that can be increased or decreased through SFML transfers.

Key Behaviors:

• Readout: Using the HAS command reads the exact integer quantity stored in the buffer.
• Comparator Integration: A Minecraft comparator adjacent to the buffer will output a signal strength based on the stored count, but it is capped at 15. For example, a buffer with a count of 16 will result in a comparator signal of 15.
• Arithmetic: Transfers between buffers conserve units. There is no underflow or overflow during transfers, and simulations are side-effect-free.
• Persistence: Redstone counts are saved in the block-entity NBT. If the NBT field is absent, the count defaults to zero. Malformed values (negative or over-capacity) are clamped during loading.
• Resource Exclusivity: A buffer maintains single-resource ownership. If a buffer is occupied by a different resource, redstone capability is declined.