trood-ontop-interface

CLI and developer-facing interface for trood-ontop.

This repository defines the stable command-line surface for trood-ontop v0.1 and delegates all structural validation and rule evaluation to the canonical validator runtime.

This repository SHALL NOT implement rule logic.

---

1. Scope

Version: v0.1 (Phase 1 Surface Freeze)

The scope of v0.1 SHALL be limited to:

• Providing a stable CLI entrypoint
• Parsing command-line arguments
• Loading input JSON files
• Delegating execution to the validator runtime
• Formatting output deterministically
• Returning stable exit codes

The interface SHALL NOT implement:

• Business logic
• Rule evaluation
• Schema validation logic
• Structural interpretation

---

2. Normative References

The following repositories are authoritative:

• trood-ontop-spec → Structural schema authority
• trood-ontop-validator → Deterministic rule execution engine
• trood-ontop → Golden conformance corpus

This repository acts strictly as a surface adapter.

---

3. Normative Language

The key words MUST, MUST NOT, SHALL, SHALL NOT, REQUIRED, SHOULD, and MAY are to be interpreted as described in RFC 2119.

---

4. Conformance Requirements

A conforming implementation MUST:

1. Load graph.json.
2. Load rules.json.
3. Invoke the validator runtime without altering inputs.
4. Format output deterministically.
5. Return stable exit codes as defined in this document.

The interface SHALL NOT reinterpret, filter, or transform rule semantics.

If validator behavior changes, the interface MUST reflect validator output faithfully and SHALL NOT introduce additional logic.

---

5. CLI Contract (v0.1)

The CLI SHALL expose the following command:

ontop validate \
  --graph graph.json \
  --rules rules.json

Run locally:

node bin/ontop.js validate --graph graph.json --rules rules.json

No additional commands are defined in v0.1.

---

6. Exit Code Contract

Exit codes SHALL be:

• 0 → No violations
• 1 → Violations detected
• 2 → Invalid input (malformed JSON or missing files)
• 3 → Internal runtime failure

Exit code semantics MUST remain stable within a MAJOR version.

---

7. Output Contract

Default output SHALL be JSON with the following structure:

{
  "violations": [...]
}

Constraints:

• Output ordering MUST be stable.
• Output structure MUST remain stable within a MAJOR version.
• The interface SHALL NOT alter violation structure returned by the validator.

Future flags MAY include:

• --format table
• --format json
• --quiet

These flags are explicitly NOT implemented in v0.1 and SHALL NOT be partially implemented.

---

8. Determinism Requirements

For identical inputs and identical validator behavior, the interface MUST produce:

• Identical output structure
• Identical ordering
• Identical exit codes

The interface SHALL NOT introduce nondeterminism via:

• Time-dependent formatting
• Random ordering
• Environment-dependent behavior

---

9. Non-Goals (v0.1)

The following are explicitly out of scope:

• Rule evaluation
• Schema validation ownership
• Extensibility systems
• Plugin support
• Web server functionality
• Graphical user interfaces

This repository defines surface only.

---

10. Architectural Position

Spec defines structure.
Validator defines rule execution.
Interface exposes surface.

The interface SHALL adapt.
It SHALL NOT reinterpret.