📐 Spec

Spec-20-Lint-Semantics

4 min readSpec contributor · SDK authorDraft · v0.9.0aN

What this spec defines

The read-only lint sweep contract, finding shape, severity mapping, filters, and async job behavior. HTTP route shape is owned by Spec-03-HTTP-API; this spec owns what a lint request means and how findings are interpreted.

Extraction status

This component spec extracts the lint semantics that previously lived in the monolithic stigmem-spec-v0.9.0a1.md lineage.

Purpose

Lint is a read-only diagnostic sweep over facts in one scope.

A lint run MUST NOT assert facts, retract facts, resolve conflicts, create or delete entities, or mutate storage state other than implementation-local job bookkeeping for asynchronous execution. Lint results are advisory.

Checks

Nodes MUST support these check names:

Check

Target

Meaning

contradiction

live facts

Report unresolved contradictions among live facts.

stale

expiry

Report live facts that are expired or will expire within the requested lookahead window.

orphan

entities

Report entities that have no live facts remaining in the requested scope.

broken_ref

references

Report live reference-valued facts whose target entity has no live facts in the requested scope.

namespacing

relations

Report live facts whose relation does not use a namespaced relation prefix.

If a lint request omits checks or supplies an empty list, the node MUST run all supported checks.

Scope and filters

Every lint run is confined to exactly one requested scope. Implementations MUST apply the caller's read authorization for that scope before inspecting facts.

Field

Optionality

Meaning

scope

required

Required scope to inspect.

checks

optional

List of check names. Empty or omitted means all checks.

entity

optional

Entity URI filter.

relation

optional

Relation filter.

stale_lookahead_s

optional

Non-negative stale lookahead window, in seconds.

Unknown scopes or check names MUST fail validation. A caller without read access to the requested scope MUST receive an authorization failure.

Finding shape

Each lint finding MUST include:

Field

Required

Meaning

check

yes

Check name that produced the finding.

severity

yes

One of error, warning, or info.

entity

yes

Entity URI most directly associated with the finding.

relation

nullable

Relation associated with the finding, or null if not applicable.

fact_ids

yes

Fact ids relevant to the finding.

detail

yes

Human-readable explanation suitable for logs and operator output.

Findings SHOULD be deterministic for a stable input store so repeated lint runs are useful in tests and operator diffs.

Severity mapping

Nodes MUST use this baseline severity mapping:

Condition

Severity

Notes

Unresolved contradiction

error

Highest priority finding.

Already-expired fact

warning

—

Expiring within stale_lookahead_s

info

—

Orphaned entity

info

—

Broken reference

warning

—

Broken intent:handoff_to/intent:context_ref

error

Promoted because handoff routing depends on these refs.

Relation without namespace prefix

warning

—

Implementations MAY add detail text, but MUST NOT downgrade the severities above.

Result shape

A completed lint run MUST return:

Field

Required

Meaning

findings

yes

List of lint findings.

checked_at

yes

Timestamp when the run completed.

scope

yes

Scope inspected.

checks_run

yes

Checks that were executed.

fact_count

yes

Number of facts considered before check-specific filtering.

HTTP and async execution

The stable HTTP lint surface includes:

POST /v1/lint
GET /v1/lint/jobs/{job_id}

Small lint runs SHOULD complete synchronously with a completed result body. Large lint runs MAY return 202 Accepted with:

Field

Type

Meaning

job_id

string

Identifier for the asynchronous lint job.

status

string

Initial job status, normally pending.

estimated_s

number

Advisory estimated completion time in seconds.

The reference node uses the configured async_job_threshold to choose the async path; its default threshold is 100,000 facts. Other conforming nodes MAY choose a different documented threshold.

Polling GET /v1/lint/jobs/{job_id} MUST eventually return either the completed lint result or a terminal failure status for known jobs. Unknown job ids MUST be reported as not found.

MCP and tooling

MCP wrappers and operator tools MUST preserve this spec's scope, check, filter, and finding semantics.

Tooling MAY present findings in a more ergonomic format, but MUST NOT hide error severity findings by default.

Out of scope

This spec does not define:

Conflict resolution

Or fact retraction workflows.

Decay/synthesis/confidence-repair

Adapter-specific context repair

Storage query plans

Or indexing strategy.

Plugin health checks

Async job queue implementation