Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 13 additions & 4 deletions client/normative/normative_claims.py
Original file line number Diff line number Diff line change
Expand Up @@ -29,19 +29,19 @@
needs a clause that states one; counting flags is not a
clause

Nothing here names a standard, a section, a field or a packet. The VITA cases
Nothing here names a standard, a section, a field or a packet. The cases
that motivated it are in the tests, not in the code.
"""

from __future__ import annotations

import os
import re
from dataclasses import dataclass, field

from normative import normative_force
from normative import normative_precedence
from normative import provision_identity
from standard import standard_profiles # noqa: F401 (registers declared role taxonomies)
from context.context_selection import SourceType

UNGROUNDED_IDENTIFIER = "UNGROUNDED_IDENTIFIER"
Expand Down Expand Up @@ -182,14 +182,23 @@
#: Shapes the identifier pattern catches that are not field names. Kept short
#: and generic: acronyms every technical document uses about ITSELF, and the
#: words a normative answer says about its own sources.
_NOT_IDENTIFIERS = frozenset({
# Common technical acronyms and the standards bodies whose names recur
# everywhere. A deployment names the bodies of its OWN corpora through
# SPEAR_STANDARD_BODIES (comma or space separated), so this public source
# carries only the ones every deployment sees and names no particular one.
_BUILTIN_NOT_IDENTIFIERS = frozenset({
"PDF", "HTML", "JSON", "XML", "ASCII", "UTF", "URL", "URI", "API", "CPU",
"GPU", "RAM", "USB", "TODO", "NOTE", "WARNING", "ERROR", "INFO", "YES",
"NO", "AND", "OR", "NOT", "THE", "ALL", "ANY", "ONE", "TWO", "MAY",
"SHALL", "SHOULD", "MUST", "RULE", "SECTION", "TABLE", "FIGURE", "ANSI",
"IEEE", "ISO", "IEC", "RFC", "NIST", "VITA",
"IEEE", "ISO", "IEC", "RFC", "NIST",
})

_NOT_IDENTIFIERS = _BUILTIN_NOT_IDENTIFIERS | frozenset(
token.upper()
for token in re.split(r"[,\s]+", os.environ.get("SPEAR_STANDARD_BODIES", ""))
if token)


def normalise(token):
"""One spelling for comparison: `Req-V`, `ReqV` and `req_v` are one name."""
Expand Down
27 changes: 27 additions & 0 deletions client/normative/normative_force.py
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@
RECOMMENDATION_FORCE: "recommendation",
REQUIREMENT_FORCE: "requirement"}

_FORCE_BY_NAME = {name: value for value, name in FORCE_NAME.items()}

# ── roles ────────────────────────────────────────────────────────────
# The names a document prints. Not an exhaustive list of what documents do:
# a taxonomy may add its own.
Expand Down Expand Up @@ -89,6 +91,31 @@ class RoleTaxonomy:
ceilings: dict = field(default_factory=dict)
default_ceiling: int = REQUIREMENT_FORCE

@classmethod
def from_mapping(cls, data):
"""Build a taxonomy from a stored profile (a standard's profile.json).

Roles are printed names (RULE, OBSERVATION …); a ceiling is a force
name (informative, permission, recommendation, requirement) or its
integer. A standard that reads its roles unconventionally ships this
beside its data in the store, so the meaning travels with the document
and no particular standard is named in this file.
"""
def as_force(value):
if isinstance(value, bool):
raise ValueError("a force is a name or an integer, not a bool")
if isinstance(value, int):
return value
return _FORCE_BY_NAME[str(value).strip().lower()]

ceilings = {role_of(role): as_force(value)
for role, value in (data.get("ceilings") or {}).items()}

return cls(name=str(data.get("name", "declared")),
ceilings=ceilings,
default_ceiling=as_force(
data.get("default_ceiling", REQUIREMENT_FORCE)))

def ceiling(self, role):
"""The strongest force a provision of this role may establish."""
return self.ceilings.get(role, self.default_ceiling)
Expand Down
13 changes: 13 additions & 0 deletions client/standard/standard_commands.py
Original file line number Diff line number Diff line change
Expand Up @@ -66,14 +66,27 @@ def active_binding(self) -> StandardBinding | None:
!= (current.retrieval_fingerprint or current.index_fingerprint)):
self._write_active(current)

self._register_profile(current)

return current

def _register_profile(self, binding) -> None:
"""Register the role taxonomy this standard ships in its store, if any.

Best-effort: a standard with no profile keeps the conventional reading.
"""
from standard import standard_profiles

standard_profiles.register_for(
self.store, binding.standard_id, binding.revision)

def use(self, standard_id: str, revision: str) -> StandardBinding:
binding = self.store.binding(
standard_id, revision,
bound_at=datetime.now(timezone.utc).isoformat(timespec="seconds"),
)
self._write_active(binding)
self._register_profile(binding)

return binding

Expand Down
77 changes: 33 additions & 44 deletions client/standard/standard_profiles.py
Original file line number Diff line number Diff line change
@@ -1,49 +1,38 @@
"""What the provision roles of a particular document mean.

The guard is generic: it knows that a role has a ceiling and that a modal
verb is evidence only up to it. WHICH ceiling belongs to WHICH role is a
statement about one document's drafting conventions, and it belongs here
rather than inside the guard.

Most specification-style documents follow the conventional reading, which is
why `normative_force.CONVENTIONAL` is the default. A profile is written when
a document's own front matter says something different, or -- as below -- when
it is worth recording explicitly that the conventional reading was checked
against the document rather than assumed.
"""
"""Per-standard role profiles, loaded from the store — never hardcoded here.

A standard whose roles mean something other than the conventional reading
(normative_force.CONVENTIONAL) ships a profile beside its ingested revision in
the store, as `profile.json`. It travels with the document into an image and is
never named in this public source; a standard with no profile uses the
conventional taxonomy. This module only knows how to load one.
"""
from __future__ import annotations

import json

from normative import normative_force as force

#: ANSI/VITA 49.2. Section 1.5 of the document sets out its own taxonomy:
#: Rules are mandatory, Recommendations are strongly advised but optional,
#: Permissions are allowances, and Observations and Definitions explain --
#: they do not oblige. That last line is the one that matters here: the
#: document contains Observations whose prose uses "must" while describing an
#: obligation a Rule imposes, and reading those as binding evidence made a
#: turn conclude that the Observation itself was the requirement.
VITA_49_2 = force.RoleTaxonomy(
name="ANSI/VITA 49.2 §1.5",
ceilings={
force.RULE: force.REQUIREMENT_FORCE,
force.REQUIREMENT: force.REQUIREMENT_FORCE,
force.RECOMMENDATION: force.RECOMMENDATION_FORCE,
force.PERMISSION: force.PERMISSION_FORCE,
force.OBSERVATION: force.INFORMATIVE_FORCE,
force.DEFINITION: force.INFORMATIVE_FORCE,
force.INFORMATIVE: force.INFORMATIVE_FORCE,
# Normative prose the document did not number, and its tables. The
# bit-assignment tables ARE the requirement a Rule points at, so a
# ceiling here would discard them.
force.UNLABELLED: force.REQUIREMENT_FORCE,
},
default_ceiling=force.REQUIREMENT_FORCE)


def install():
"""Register every declared profile. Idempotent."""
force.register_taxonomy("ANSI-VITA-49.2", VITA_49_2)


install()
PROFILE_FILE = "profile.json"


def register_for(store, standard_id, revision):
"""Register the role taxonomy a standard ships in its store, if any.

Best-effort and idempotent: a missing or unreadable profile leaves the
conventional reading in place, so a broken file never blocks a binding.
"""
try:
path = store.revision_dir(standard_id, revision) / PROFILE_FILE
except Exception:
return None

if not path.is_file():
return None

try:
taxonomy = force.RoleTaxonomy.from_mapping(
json.loads(path.read_text("utf-8")))
except Exception:
return None

return force.register_taxonomy(standard_id, taxonomy)
2 changes: 1 addition & 1 deletion client/tests/synthetic_standard.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
The harness is bound, in production, to documents somebody licensed. Their
clause text is theirs: it may be ingested into a user's own runtime state and
read from there, and it may not be copied into this repository. Identifiers
are a different matter -- "ANSI-VITA-49.2", "§8.4.1.1", "AckV" name a thing
are a different matter -- "EXAMPLE-STD-1.0", "§8.4.1.1", "AckV" name a thing
without reproducing it, and a test about binding or about name plumbing is
entitled to use the real ones.

Expand Down
2 changes: 1 addition & 1 deletion client/tests/test_abstention_complement.py
Original file line number Diff line number Diff line change
Expand Up @@ -279,7 +279,7 @@ def test_identities_are_unique(self):

def test_no_scenario_mentions_an_evaluated_document(self):
blob = " ".join(serialize(item) for item in COMPLEMENT_SCENARIOS).lower()
for absent in ("vita", "49.2", "ansi", "vrt"):
for absent in ("example-std", "1.0", "ansi", "vrt"):
self.assertNotIn(absent, blob)

def test_no_scenario_reaches_the_held_out_evaluation_cases(self):
Expand Down
2 changes: 1 addition & 1 deletion client/tests/test_abstention_pressure.py
Original file line number Diff line number Diff line change
Expand Up @@ -225,7 +225,7 @@ def test_no_pressure_question_repeats_an_earlier_pool_question(self):

def test_no_scenario_mentions_an_evaluated_document(self):
blob = " ".join(serialize(item) for item in PRESSURE_SCENARIOS).lower()
for absent in ("vita", "49.2", "ansi", "vrt", "beamwidth"):
for absent in ("example-std", "1.0", "ansi", "vrt", "beamwidth"):
self.assertNotIn(absent, blob)

def test_every_failing_gap_type_has_a_control_of_the_same_kind(self):
Expand Down
2 changes: 1 addition & 1 deletion client/tests/test_abstention_scenarios.py
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ def test_substituting_a_family_changes_only_the_vocabulary(self):

def test_no_scenario_mentions_an_evaluated_document(self):
blob = " ".join(serialize(item) for item in SCENARIOS).lower()
for absent in ("vita", "49.2", "ansi", "vrt"):
for absent in ("example-std", "1.0", "ansi", "vrt"):
self.assertNotIn(absent, blob)


Expand Down
4 changes: 2 additions & 2 deletions client/tests/test_agent_runtime.py
Original file line number Diff line number Diff line change
Expand Up @@ -1137,14 +1137,14 @@ class WhoIsAskingTests(unittest.TestCase):
def test_a_harness_nudge_is_not_the_users_request(self):
conversation = [
ConversationMessage("user", (TextBlock(
"How should the ACK be managed in VITA 49.2?"),)),
"How should the ACK be managed in EXAMPLE-STD-1.0?"),)),
ConversationMessage("assistant", (TextBlock("Rule 8.4.1.1-2 ..."),)),
ConversationMessage("user", (TextBlock("Conclude now and fix it."),),
authored_by="harness"),
]

self.assertEqual(_asked(conversation),
"How should the ACK be managed in VITA 49.2?")
"How should the ACK be managed in EXAMPLE-STD-1.0?")
self.assertFalse(is_write_request(_asked(conversation)))

def test_the_conclude_nudge_would_read_as_a_write_request(self):
Expand Down
2 changes: 1 addition & 1 deletion client/tests/test_carried_spec.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ def test_the_users_own_second_prompt(self):

def test_the_first_prompt_carries_nothing(self):
self.assertFalse(is_write_request(
"How should the ACK be managed when using VITA49.2 Commands packets?"))
"How should the ACK be managed when using EXAMPLE-STD-1.0 Commands packets?"))


class TheContextCarriesIt(unittest.TestCase):
Expand Down
2 changes: 1 addition & 1 deletion client/tests/test_change_claims.py
Original file line number Diff line number Diff line change
Expand Up @@ -181,7 +181,7 @@ def test_the_forms_a_write_request_takes(self):
self.assertTrue(is_write_request(question))

def test_a_question_keeps_both_branches(self):
for question in ("How should the ACK be managed with VITA49.2?",
for question in ("How should the ACK be managed with EXAMPLE-STD-1.0?",
"what does Rule 8.4.1.1-3 require?",
"explain how cmdlink.c dispatches a request"):
with self.subTest(question=question):
Expand Down
Loading
Loading