axone-logic-predicate

name	axone-logic-predicate
description	Add or change predicates in the AXONE logic module. Use when working on x/logic predicate behavior, Prolog libraries, predicate docs, VFS-backed logic capabilities, or feature scenarios. Follows the current architecture direction: new predicates should be written in Prolog, either pure Prolog or Prolog backed by the path-based logic VFS, not as new native Go predicates.
compatibility	Requires go, make, and docker for validation and doc generation.

Axone Logic Predicate

Use this skill when changing predicate behavior in x/logic.

Architectural direction

New predicates should not be introduced as native Go predicates in x/logic/predicate or registered through x/logic/interpreter/registry.go.

The target model is:

1. pure Prolog predicates implemented in x/logic/lib/*.pl, or
2. Prolog predicates implemented in x/logic/lib/*.pl and backed by the path-based logic VFS for host I/O.

For transactional endpoints, use the existing device-file model: path-based VFS access plus a half-duplex request/commit/response interaction pattern.

Treat x/logic/predicate and the interpreter registry as existing runtime primitives and legacy surface area. Change them only for maintenance, bug fixes, or truly unavoidable interpreter-level work. If you need to touch them for new functionality, call that out explicitly as an architectural exception.

Choose the implementation shape

• If the behavior can be expressed by composing existing predicates and libraries, implement it as pure Prolog in x/logic/lib/*.pl.
• If the behavior needs host data or external capabilities, expose that capability through the VFS under x/logic/fs/**, then wrap it with a Prolog predicate in x/logic/lib/*.pl.
• If the behavior is an interactive transactional endpoint, expose it under /v1/dev/... and use the device helpers from x/logic/lib/dev.pl.
• Do not add a new Go predicate when a Prolog wrapper over open/4, read_term/3, write_term/3, or dev_call/4 would solve the problem.

VFS model

The logic VFS is the boundary between logical evaluation and host capabilities.

• /v1/lib: embedded Prolog libraries
• /v1/run: invocation-scoped runtime resources
• /v1/var/lib: persistent host-managed resources
• /v1/dev: interactive device-like capabilities

Choose the path family that matches the semantics:

• Snapshot or read-only runtime state: prefer /v1/run/...
• Persistent queryable resources: prefer /v1/var/lib/...
• Request-response endpoints: prefer /v1/dev/...

For /v1/dev/... endpoints, keep the protocol aligned with the existing half-duplex model:

1. writes build the request
2. the first read commits the transaction
3. subsequent reads stream the response

Implementation patterns

Public textual representation

Public domain predicates must use atoms as the canonical representation for textual inputs and outputs. Do not make a public predicate accept atoms, character lists, and character code lists through a broad text contract unless representation conversion is the predicate's explicit purpose.

• Use must_be(atom, Value) at public predicate boundaries for textual values.
• Return textual values as atoms.
• Keep byte payloads as list(byte) when the API is explicitly byte-oriented.
• Leave conversion predicates such as atom_chars/2, atom_codes/2, string_bytes/3, and stream-reading helpers responsible for representation conversion.
• Require callers to perform explicit conversions before calling domain predicates when they hold character lists or code lists.

Pure Prolog predicate

• Add or update a library file in x/logic/lib/*.pl
• Validate inputs with with_context/2 and must_be/2 when appropriate
• Use setup_call_cleanup/3 around stream access
• Write PlDoc comments because make doc-predicate depends on them

VFS-backed predicate

• Implement the host-facing filesystem in x/logic/fs/**
• Mount it through the standard VFS if it is part of the canonical host surface
• Expose an ergonomic Prolog predicate in x/logic/lib/*.pl
• Prefer returning logical terms from Prolog wrappers, not leaking protocol details unless the predicate is intentionally low-level

Transactional device-backed predicate

• Reuse dev_call/4, dev_write_bytes/2, and dev_read_bytes/2 from x/logic/lib/dev.pl
• Encode protocol errors in-band when designing the device protocol
• Keep transport details inside the VFS device and Prolog wrapper; keep the public predicate ergonomic
• Follow the pattern used by wasm_query/3 and codec-backed helpers

Documentation contract

For Prolog predicates, documentation is not optional. The generated predicate docs depend on the source comments.

• Put a %! signature line immediately above the predicate definition, for example %! wasm_query(+Address, +RequestBytes, -ResponseBytes) is det.
• Continue the doc block with % comment lines directly above the predicate head.
• Keep the doc block attached to the predicate. The generator reads the contiguous % block and associates it with the next predicate head.
• Document the public predicate, not just helper predicates.
• Include enough description for the generated ## Description section to stand on its own.
• Mention loading expectations when relevant, but do not duplicate the auto-generated consult('/v1/lib/...') section in prose.

Feature contract

Every predicate change should come with feature coverage in x/logic/tests/predicate/features.

• Name the feature file after the predicate, using the generated doc naming convention: name_arity.feature for name/arity.
• Start with Feature: name/arity.
• Add scenarios for the main success path and important failure paths.
• Mark the scenarios that should appear in generated docs with @great_for_documentation.
• Treat features as both executable tests and documentation examples. Keep them readable and domain-oriented.
• When the predicate is provided by a library file under /v1/lib, include the explicit consult('/v1/lib/...'). step in the scenario program unless the scenario is specifically testing availability before consult.

Files to update

• Predicate API: x/logic/lib/*.pl
• Host capability surface: x/logic/fs/**
• Predicate feature coverage: x/logic/tests/predicate/features/*.feature
• Predicate docs generator inputs: PlDoc in x/logic/lib/*.pl

Only touch these for exceptions or maintenance:

• x/logic/predicate/*.go
• x/logic/interpreter/registry.go

Validation

• Run make doc-predicate
• Run make test-go
• If you changed Go code under x/logic/fs/** or related plumbing, also run make lint-go

Gotchas

• make doc-predicate still scans both Go predicates and Prolog predicates. That is a generator detail, not a design recommendation.
• New .pl files under x/logic/lib are embedded automatically and become available under /v1/lib/....
• Feature files under x/logic/tests/predicate/features are both behavioral tests and documentation inputs. Only scenarios tagged @great_for_documentation are rendered into generated docs.
• dev_call/4 is the preferred low-level abstraction for transactional endpoints. Build a higher-level domain predicate on top of it instead of exposing raw device usage directly to callers when possible.
• If a predicate should be auto-loaded as part of the interpreter bootstrap rather than explicitly consulted from /v1/lib/..., treat that as a special case and justify it before editing bootstrap files.

Read first

• x/logic/fs/std_fs.go
• x/logic/lib/dev.pl
• x/logic/lib/wasm.pl
• x/logic/tests/predicate/features/dev_call_4.feature
• scripts/generate_predicates_doc.go