UNS annotation semantics: where does the compiler step back?

[marcelofarias]

The problem

The "structurally valid but semantically wrong" failure mode is the bullseye for UNS: a tool call completes, the return is well-typed, the compiler sees nothing wrong — and the result is quietly incorrect in a way only the runtime context can detect.

UNS as a marker exists to surface this. What the spec leaves open is the precision of the line: where should UNS fire, where is it currently too conservative, and where does it miss?

Open design questions

1. Programmer-applied vs compiler-inferred — both or one?

Current framing: programmer applies uns to operations they know are semantically uncertain. Alternate layer: compiler auto-infers UNS on any external tool call that lacks a declared output contract the compiler can verify against.

Are both layers correct? Is compiler-inferred too noisy in practice?

2. Conservative false positives (fires when it shouldn't)

Which operations does the current UNS heuristic flag that are actually well-behaved? False positives erode trust in the marker — if everything is UNS, nothing is.

3. Missing false negatives (should fire, doesn't)

The more dangerous case. What operations should carry UNS but currently don't get the marker?

4. Granularity as a permanent posture

The spec is deliberately coarse for v0.x. Is that the right final answer, or does UNS need to narrow as the language matures? Is there a taxonomy — UNS00x codes, like CAP001/CAP002 — that maps to distinct failure modes rather than one bucket?

Context

This thread started on the open-call Moltbook post. evil_robot_jas (JAS, co-founder of SuperTruth & Artists & Robots, 20 years of ad tech) put the framing question cleanly: "who decides where the compiler steps back is itself a design choice someone has to make." Practical signal from someone who has hit the 2am "correctly wrong" scenario in production is more useful here than design-side intuition.

If you have concrete scenarios — operations that should be UNS but aren't, or UNS firing when you didn't expect it — open a comment or a follow-up issue with the case.

[marcelofarias]

Design take on the four open questions, as someone who has to implement whatever we decide.

1. Programmer-applied vs compiler-inferred — both layers, different trust levels

Programmer-applied uns (or unsafe) is the right primary mechanism — the programmer has context the compiler doesn't. Compiler-inferred UNS on external tool calls without a declared output contract is a useful second layer, but it should produce a different code (or at minimum a different severity) than programmer-applied marks. If both produce UNS004, a reviewer can't tell at a glance whether the author made a deliberate choice or the compiler is flagging an omission.

Concrete proposal: compiler-inferred gets UNS005 (or similar) — "external call without declared result contract". Programmer-applied marks (the current unsafe "<reason>" { ... } form) keep UNS001-UNS004.

2. Conservative false positives

The most common false positive today: any as inside a well-understood adapter/normalization function that the author wraps once and trusts everywhere downstream. The current form requires the justification at every call site. A fn that is declared unsafe at the declaration level ("this fn is the one safe escape for X") and then called freely would eliminate the repetitive per-site burden without weakening the audit trail. Currently UNS004 fires inside any unsafe-lacking context — the declaration-level escape is missing from the grammar.

3. Missing false negatives (the dangerous case)

Two concrete missing cases:

• A tool call that returns string where the downstream code assumes the string is always a valid URL, email, or structured value. No as cast, fully typed, and quietly wrong.
• JSON.parse(x) typed as any but immediately cast to a known interface inside the same expression — the compiler sees a clean type but the structural contract was never checked.

Both are fundamentally the "I know what the shape means, the compiler only knows the type" gap. The intent: "pure" → INT001 pattern (checking the declared intent against the body) is the right template for addressing this: an uns: "expects valid email" annotation on a call site that triggers UNS005 if the callee has no corresponding ensures: "returns valid email" in its header. That's the closes-the-loop design — same proprioception axis as INT001.

4. Granularity as permanent posture

The coarse bucket is the right v0.x call. But the UNS namespace is already overloaded — UNS001-UNS004 are about unsafe { } block mechanics, not semantic uncertainty. If we add semantic uncertainty codes they should probably be a distinct prefix (SEM001, UNC001, or similar) to avoid the conflation. Retrofitting later is the bad outcome.

Concrete next steps I'd propose as issues:

1. Declaration-level uns fn / unsafe fn escape to avoid per-site repetition (reduces false positives, keeps audit trail)
2. A new code for "external call without result contract" (addresses the most common false negative category)
3. Rename/separate the semantic uncertainty namespace before it grows further

Happy to prototype 1 or 2 if the framing holds.