​

SPEC-039: NYI Runtime Contract — Stub/Placeholder Signaling for Prism Verbs

​

Version

​

Status

​

Origin

​

§1 — Canonical Response Shape

{
  "status": "not_yet_implemented",
  "code": "NYI",
  "verb": "<verb_name>",
  "tracking_spec": "SPEC-XXX",
  "tracking_issue": "<url-or-id>",
  "message": "<one-line human description>",
  "since_constitution_version": "<bios_version-when-declared>"
}

• MCP / JSON-RPC: structured response with status: "not_yet_implemented", result is the payload above. NOT an exception — callers should be able to introspect without try/except.
• HTTP / REST: status 501 Not Implemented, body is the canonical payload above. Standard HTTP semantics — meets caller expectations.
• gRPC: status code UNIMPLEMENTED (12), trailer carries serialized canonical payload.

​

§2 — Source-Level Marker Convention

​

§3 — Helper API

def prism_nyi_response(
    verb: str,
    tracking_spec: str = "",
    tracking_issue: str = "",
    message: str = "",
    since: str = "",
) -> dict:
    """Return the canonical NYI payload."""

def prism_nyi(verb: str, tracking_spec: str = "", message: str = ""):
    """Decorator: replace the wrapped function's body with the NYI payload."""

# PRISM-NYI: hd_exec is constitutional vaporware [tracking: SPEC-040]
@prism_nyi(verb="hd_exec", tracking_spec="SPEC-040",
           message="Symmetric pickup to prism_wrap; see SPEC-040.")
async def hd_exec(pid: str) -> dict:
    ...  # body never runs

async def some_verb(pid, mode):
    if mode == "experimental":
        # PRISM-NYI: experimental mode pending [tracking: SPEC-XXX]
        return prism_nyi_response(
            verb="some_verb",
            tracking_spec="SPEC-XXX",
            message="experimental mode not yet implemented",
        )
    ...  # real path

​

§4 — prism_audit Integration

{
  "stubs_in_source": [
    {
      "verb": "hd_exec",
      "file": "mcp/server.py",
      "line": 2310,
      "tracking_spec": "SPEC-040",
      "reason": "constitutional vaporware",
      "marker_kind": "decorator"
    }
  ],
  "constitution_refs": [
    {
      "file": "PRISM.md",
      "line": 88,
      "verb": "hd_exec",
      "marker_present": false,
      "tracking_spec": null
    }
  ],
  "summary": {
    "total_stubs": 1,
    "tracked": 1,
    "untracked": 0,
    "constitution_refs_unmarked": 4
  },
  "exit_status": "fail"
}

​

§5 — Verification

1. Calling a verb decorated with @prism_nyi(...) returns the canonical payload with all required fields.
2. Calling a stub verb with deliberately malformed inputs (e.g., hd_exec(pid=42)) returns the SAME canonical NYI payload — no validation interception (per Q1 decision).
3. prism_audit lists every PRISM-NYI marker in mcp/, backend/, cli/, bin/.
4. prism_audit returns exit_status: "fail" when an untracked stub exists or a constitution ref lacks the annotation.
5. After SPEC-040 ships and removes hd_exec’s NYI marker, prism_audit no longer lists it under stubs_in_source and exit_status flips back to ok (assuming no other untracked stubs).
6. HTTP wire test: a REST call to an NYI endpoint returns 501 with the canonical body.
7. gRPC wire test: an UNIMPLEMENTED status carries the canonical payload in trailer metadata.

​

§6 — Decisions

• Q1 (input validation in stubs): SKIPPED / settled — orthogonal to the dual-signal architecture (return code + source marker) which already addresses the “don’t forget” goal. Stubs do not validate inputs; validation logic belongs to the real implementation.
• Q2 (audit failure mode): HYBRID. Tracked stubs (with tracking_spec) are advisory. Untracked stubs AND constitution refs missing the marker cause prism_audit to return exit_status: "fail" and non-zero CLI exit. Forces every stub to be either implemented or explicitly declared.
• Q3 (marker token): PRISM-NYI. Namespaced (won’t false-positive on grep), brand-consistent with PRISM_AGENT_IDENTITY / prism_*, self-documenting. Applied across all source types per §2.