Skip to content

Cache.md

Latest commit

 

History

History
694 lines (544 loc) · 19.8 KB

Cache.md

File metadata and controls

694 lines (544 loc) · 19.8 KB

FROG logo

🐸 FROG Cache Specification

Definition of optional non-authoritative cache data for .frog programs
FROG — Free Open Graphical Language

Contents

1. Overview

The cache mechanism stores optional derived data associated with a FROG program. Its purpose is to accelerate tooling workflows such as loading, validation, indexing, analysis, lowering preparation, compilation preparation, and execution-oriented representation generation.

A common use case is caching an execution-oriented intermediate representation derived from the canonical source .frog file. However, cache is not limited to execution-oriented representations and MAY also contain other derived artifacts useful to tools.

Cache data is non-authoritative. The meaning of a FROG program is always defined by canonical source, never by cache content.

Accordingly:

  • cache data MUST NOT define program semantics,
  • cache data MUST NOT redefine typing, scheduling, structure identity, or observable behavior,
  • cache data MUST be safe to delete and regenerate.

2. Scope

This document specifies:

  • the role of optional cache artifacts associated with a FROG,
  • the boundary between canonical source and derived cache,
  • supported cache storage forms,
  • a generic cache container structure,
  • correctness, validation, and stale-cache handling rules.

This document does not specify:

  • the canonical source representation itself,
  • the normative execution semantics of the language,
  • the definitive standard execution IR,
  • the internal architecture of a particular IDE, compiler, or runtime,
  • distribution artifacts such as .frogbin.

3. Relation with Other Specifications

The optional top-level cache section belongs to the canonical source specification in Expression/ when cache is embedded inside a .frog file.

However, the same cache model MAY also be serialized as an external sidecar artifact in a separate .frog.cache file.

Its ownership boundary relative to neighboring source and tooling artifacts is: 

Source and tooling boundary

metadata    - descriptive program identity
interface   - public typed program boundary
diagram     - authoritative executable graph
front_panel - optional user-facing interaction composition
icon        - optional reusable-node visual identity
ide         - optional IDE-facing authoring preferences and recoverability metadata
cache       - optional derived data for tooling acceleration

Canonical source owns meaning.
Cache owns no meaning.

In particular:

  • cache does not define executable logic. That belongs to canonical source, especially diagram.
  • cache does not define public API. That belongs to interface.
  • cache does not define descriptive identity. That belongs to metadata.
  • cache does not define editor recoverability or source-carried authoring preferences. That belongs to ide.

A practical distinction is: 

If the data is:
- authoritative and needed to understand the program -> canonical source
- useful to reopen or author more comfortably        -> ide
- derived, optional, and safe to regenerate          -> cache

4. Design Goals

  • Speed up loading, validation, lowering, and compilation workflows.
  • Avoid recomputing derived artifacts when authoritative source has not changed.
  • Keep canonical source authoritative and transparent.
  • Allow cache to be safely deleted, ignored, or regenerated.
  • Prevent cache data from redefining execution semantics.
  • Support clean version-control workflows with minimal diff noise.

5. Cache Storage Options

FROG supports two cache storage options:

  • Preferred: a separate sidecar cache file (.frog.cache)
  • Allowed but secondary: an embedded cache object inside the canonical .frog file

The sidecar file is preferred because it keeps canonical source cleaner and reduces noisy diffs, merge conflicts, and unnecessary version-control churn.

Embedded cache is still allowed for workflows where portability, single-file transport, or source-attached derived artifacts are desirable.

6. External .frog.cache File

A cache sidecar file is associated with a source file by name. 

example.frog
example.frog.cache

The external cache file MAY be generated automatically by tooling and MAY be deleted at any time. Tools SHOULD regenerate it when needed.

The external cache file is a derived artifact. It is not part of the authoritative source definition of the program.

The sidecar form is the preferred storage strategy for routine tooling workflows.

7. Embedded cache Object

In some workflows, tools MAY embed cache data directly inside the canonical .frog file as an optional top-level cache object.

If embedded, the cache object:

  • MUST remain optional,
  • MUST remain non-authoritative,
  • MUST NOT be required for correctness,
  • MUST be safe to remove without changing program meaning.

Embedded cache is allowed for convenience, but it is generally less desirable than a sidecar file for collaborative source-control workflows.

8. Cache Model

The cache model is intentionally simple: 

Canonical source and derived cache

authoritative source
     |
     v
+----------------------+
|     example.frog     |
|----------------------|
| metadata             |
| interface            |
| connector            |
| diagram              |
| front_panel          |
| icon                 |
| ide                  |
| cache (optional)     |
+----------+-----------+
           |
           | derived from authoritative source
           v
+----------------------+
| source_fingerprint   |
+----------+-----------+
           |
           v
+----------------------+
| entries              |
|----------------------|
| frog.ir              |
| frog.validation      |
| frog.analysis        |
| tool-specific data   |
+----------------------+

Cache can be:
- embedded inside .frog
- external in .frog.cache

In all cases cache is:
- derived
- optional
- non-authoritative
- safe to delete

The cache container is a derived snapshot keyed to some identifiable source state. When that source state changes, the cache MAY become stale and SHOULD be treated accordingly.

9. Cache Object Structure

Recommended cache structure: 

"cache": {
  "format_version": "0.1",
  "generator": {
    "tool": "frog-ide",
    "version": "0.1.0"
  },
  "source_fingerprint": "sha256:...",
  "entries": {
    "frog.ir": {
      "kind": "execution_ir",
      "schema_version": "0.1",
      "created": "2026-03-05T12:00:00Z",
      "depends_on": ["interface", "diagram", "front_panel"],
      "data": {}
    }
  }
}

This structure is generic enough to support multiple derived artifacts while keeping a stable, simple contract.

10. Top-Level Fields

10.1 format_version

Version of the cache container format.

  • MUST be a string if present.
  • SHOULD identify the cache-container schema version.

10.2 generator

Describes the tool that generated the cache. 

"generator": {
  "tool": "frog-ide",
  "version": "0.1.0"
}
  • MUST be an object if present.
  • All generator fields are informational only.
  • MUST NOT affect program meaning.

10.3 source_fingerprint

Fingerprint of the authoritative source state from which the cache was derived.

  • MUST be a string if present.
  • SHOULD be stable for identical authoritative source content.
  • SHOULD change when authoritative source content changes.
  • Tools MUST treat cache as stale if the fingerprint does not match the current authoritative source state.

10.4 entries

Collection of named cache entries.

  • MUST be an object if present.
  • Each property name identifies one cache entry.
  • Unknown entries MUST be safely ignorable.

Recommended naming:

  • frog.* for project-defined common entries
  • reverse-domain prefixes for tool-specific entries

Examples:

  • frog.ir
  • frog.validation
  • frog.analysis
  • com.graiphic.ide.symbol_index

10.5 Entry Structure

Each entry SHOULD follow this general structure: 

"frog.ir": {
  "kind": "execution_ir",
  "schema_version": "0.1",
  "created": "2026-03-05T12:00:00Z",
  "depends_on": ["interface", "diagram", "front_panel"],
  "data": {}
}
  • kind — high-level category of cache entry
  • schema_version — version of the entry payload schema
  • created — creation timestamp in ISO-8601 UTC form
  • depends_on — source sections or stable dependency identifiers
  • data — opaque JSON payload containing the derived artifact

The data field MAY contain any valid JSON value, but it MUST contain only derived information.

11. Common Cache Entry Kinds

11.1 Execution IR Cache

Stores a cached execution-oriented intermediate representation derived from authoritative source.

This is a common and important cache use case. It is intended to accelerate repeated validation, lowering, compilation preparation, and execution preparation.

11.2 Validation Cache

Stores derived validation outcomes, such as:

  • validation status,
  • diagnostic counts,
  • resolved warning sets,
  • last validated profile or target context.

11.3 Analysis Cache

Stores derived structural information, such as:

  • symbol indexes,
  • dependency analysis results,
  • graph summaries,
  • editor lookup tables.

11.4 Tool-Specific Cache

Tools MAY store private derived data under their own namespace, provided that the data remains optional, safe to ignore, and non-authoritative.

12. Authority and Correctness Rules

Cache data MUST be treated as an optimization only.

  • Runtimes MUST NOT require cache data to execute a program correctly.
  • Runtimes MUST NOT trust cache data as authoritative truth.
  • Tools MUST be able to rebuild needed cache data from authoritative source.
  • If cache conflicts with authoritative source content, authoritative source content MUST win.
  • Removing cache MUST NOT change the meaning of the program.

Embedded cache does not become authoritative merely because it is physically stored inside the .frog file. Its storage location does not change its semantic status.

Source provenance is not cache. An attestation stored under ide.provenance may include a signature, issuer, digest, or human-review claim for a specific source state. Such evidence is source-carried audit metadata and SHOULD NOT be discarded merely because it is non-executable or because a formatter normally removes derived cache entries. 

Authority rule

canonical source -> authoritative
embedded cache   -> not authoritative
sidecar cache    -> not authoritative

Physical proximity to source
does not create semantic authority.

13. Stale, Invalid, or Partial Cache Handling

Cache data SHOULD be treated as stale when:

  • source_fingerprint does not match the current authoritative source content,
  • format_version is not supported,
  • an entry schema_version is not supported,
  • an entry payload fails validation,
  • required dependencies listed in depends_on have changed,
  • the cache payload is incomplete or corrupted.

When cache is stale or invalid:

  • tools SHOULD discard the invalid portion and regenerate it,
  • runtimes MUST ignore cache for correctness decisions,
  • tools MAY keep valid entries and regenerate only stale ones.

A malformed or stale cache MUST degrade performance at worst, not correctness.

14. Security Considerations

Cache content MUST NOT be treated as executable truth.

  • Tools SHOULD validate cache payloads before use.
  • Runtimes MUST validate source-derived executable representations regardless of cache presence.
  • Tools SHOULD avoid storing secrets or sensitive information in cache.
  • Cache data MAY be treated as untrusted input.

A malformed cache file MUST NOT compromise correctness. At worst, it should be ignored and regenerated.

15. Validation Rules

Implementations MUST enforce the following rules:

  • If present, embedded cache MUST be a JSON object.
  • If present, external .frog.cache root content MUST be a JSON object.
  • If present, format_version MUST be a string.
  • If present, generator MUST be an object.
  • If present, source_fingerprint MUST be a string.
  • If present, entries MUST be an object.
  • Each entry value inside entries MUST be an object.
  • If present, entry kind MUST be a string.
  • If present, entry schema_version MUST be a string or integer.
  • If present, entry created MUST be a string.
  • If present, entry depends_on MUST be an array of strings.
  • Entry data MAY be any valid JSON value.
  • Unknown cache entries MUST be ignorable.
  • Invalid, unreadable, stale, or incompatible cache MUST NOT change correctness.

16. Examples

16.1 Minimal Embedded Cache Object

"cache": {
  "format_version": "0.1",
  "source_fingerprint": "sha256:...",
  "entries": {
    "frog.ir": {
      "kind": "execution_ir",
      "schema_version": "0.1",
      "data": {}
    }
  }
}

16.2 Extended Embedded Cache Object

"cache": {
  "format_version": "0.1",
  "generator": {
    "tool": "frog-ide",
    "version": "0.1.0"
  },
  "source_fingerprint": "sha256:7d1b...c9",
  "entries": {
    "frog.ir": {
      "kind": "execution_ir",
      "schema_version": "0.1",
      "created": "2026-03-05T12:00:00Z",
      "depends_on": ["interface", "diagram", "front_panel"],
      "data": {
        "graph": {},
        "types": {}
      }
    },
    "frog.validation": {
      "kind": "validation",
      "schema_version": "0.1",
      "created": "2026-03-05T12:00:01Z",
      "depends_on": ["interface", "diagram"],
      "data": {
        "valid": true,
        "errors": []
      }
    }
  }
}

16.3 External Sidecar Cache File

{
  "format_version": "0.1",
  "generator": {
    "tool": "frog-cli",
    "version": "0.1.0"
  },
  "source_fingerprint": "sha256:7d1b...c9",
  "entries": {
    "frog.ir": {
      "kind": "execution_ir",
      "schema_version": "0.1",
      "created": "2026-03-05T12:00:00Z",
      "depends_on": ["interface", "diagram", "front_panel"],
      "data": {
        "graph": {}
      }
    }
  }
}

17. Summary

The cache mechanism provides optional acceleration for tooling workflows.

  • Preferred storage is a separate .frog.cache file.
  • Embedded cache is allowed but secondary.
  • Cache data is derived, optional, and non-authoritative.
  • Execution-oriented IR is a primary cache use case, but not the only one.
  • Authoritative source content always defines program meaning.

In FROG: 

source is authoritative
cache is derived
cache is optional
cache is disposable