jacobian: Instructions file for Codex

Jacobian agent guide

Jacobian gives agents atomic, composable tools for higher mathematics. math.find discovers immutable operation declarations; math.run executes one bounded typed computation. The caller owns reasoning, composition, and durable state. The native mathematical library is independent of discovery and MCP; tool declarations publish its capabilities, and delivery adapters expose them. Use “operation” or “math tool,” not “product” or “provider,” for built-ins.

Product invariants

• Atomicity is semantic: one operation establishes one stable, reusable mathematical postcondition. Alternative algorithms remain private kernel choices. Discovery describes mathematics, not a proof strategy or call order.
• Keep the kernel stateless. Temporary execution state is request-scoped. Return mathematical values directly, without generic assurance, verification, obligation, or completeness wrappers. Operational non-completion never establishes a mathematical conclusion.
• Return ordinary exact values without certificates, source digests, or verified flags by default. Include a witness only for the operation's mathematical purpose. A consumer checks an authored relation only when its result relies on it; it does not verify a value's entire producer history.
• Built-ins are immutable MathTool tuples in owner-local _tools.py manifests under jacobian.math. Manifest presence is publication; catalog construction fails closed on malformed declarations and duplicate IDs.
• Reuse domain-owned canonical values across producers and consumers, including empty and degenerate cases. Keep mathematical values, operation arguments, wire envelopes, and execution context distinct. Representation variants need explicit semantics; changes of ring, field, parent, or axes need typed maps.
• Bound parsing, allocation, computation, and delivery at their owning boundaries. Admit work, growth, and exact output before backend expansion; native admission must not inherit a deployment's wire-byte ceiling.
• Check each relied-upon invariant at its owning trust boundary. Reuse admission facts and avoid repeating expensive solves during construction or decoding; retain structural and admitted candidate/claim checks needed for correctness. Moving checks out of constructors requires migrating every dependent consumer.
• Compute with native exact scalars and encode them only at wire boundaries. Raw preflight preserves scalar representation for the shared codec. Exact encoding of a numerical approximation does not establish exact mathematics.
• Scale first: probe a motivating rejected request, improve the estimate, representation, algorithm, or backend, and retain cheaply executable cases as accepted regressions. Measurements do not replace a sound bound. A remaining limitation must be reported, not presented as a completed scale repair.
• Prefer maintained mathematical backends through thin typed adapters. Jacobian owns the accepted contract; backend exceptions cannot define it. A subprocess needs a concrete isolation, killability, or fixed-toolchain reason. All mandatory phases share the request's deadline and work accounting; wall time is a safety limit, not mathematical evidence or a universal short timeout.
• Mathematical syntax has a named, non-evaluating grammar. Caller strings must never reach sympify, parse_expr, eval, exec, or generated evaluators.
• Jacobian is pre-stable: repair an unsound contract rather than preserving it through compatibility machinery. Diagnose operation, representation, interoperability, discovery, contract, scale/backend, and reasoning gaps before proposing a new public operation.