The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.
JavaScript
"""The entity and connection vocabularies (ONTOLOGY §§2–3).
Families organize the board; each verb still declares the concrete endpoints that
make semantic sense. A new type therefore joins no connection accidentally. This
file locks the exact matrix exposed by the API and enforced on writes.
"""
from pathlib import Path
import pytest
from azimut.engine import artifacts
from azimut.engine import entities
from azimut.engine import links as link_engine
from azimut.sqlite_backend import SQLITE_SCHEMA
from azimut.workspace import CASE_SCHEMA, Case, CaseError
def _new_case(client, name):
return client.post("/api/cases", json={"name": name}).json()["id"]
def _link(client, cid, from_id, to_id, type_):
return client.post(
f"/api/cases/{cid}/links",
json={"from_id": from_id, "to_id": to_id, "type": type_},
)
# -- the registry -------------------------------------------------------------
def test_the_vocabulary_says_each_types_family_reading_and_fields(client):
rows = {row["type"]: row for row in client.get("/api/cases/entity-types").json()}
assert rows["person"]["family"] == "actor"
assert rows["person"]["manual"] is True
assert rows["vessel"]["family"] == "asset"
assert rows["media"]["family"] == "collected"
assert rows["proof"]["family"] == "document"
assert rows["place"]["family"] == "place"
assert rows["person"]["identity_label"] == "Full name"
assert rows["ip"]["identity_label"] == "IP address"
assert rows["ip"]["identity_placeholder"] == "203.0.113.42"
# the fields are what lets one generated form serve every hand-made type
assert [attr["key"] for attr in rows["aircraft"]["attrs"]] == [
"registration",
"icao24",
"model",
"condition",
]
kinds = {attr["key"]: attr["kind"] for attr in rows["account"]["attrs"]}
assert kinds["url"] == "url"
def test_identifiers_expose_the_value_field_and_relevant_context(client):
rows = {row["type"]: row for row in client.get("/api/cases/entity-types").json()}
assert [attr["key"] for attr in rows["ip"]["attrs"]] == [
"network",
"asn",
"provider",
]
assert rows["ip"]["attrs"][0]["editable"] is False
assert rows["network"]["identity_label"] == "Network or CIDR"
assert [attr["key"] for attr in rows["network"]["attrs"]] == [
"asn",
"provider",
"country",
]
# The handle is the account's label. A second handle field could disagree.
assert "handle" not in {attr["key"] for attr in rows["account"]["attrs"]}
def test_the_legacy_ip_network_field_is_read_only(client):
cid = _new_case(client, "Legacy IP field")
created = client.post(
f"/api/cases/{cid}/entities",
json={
"type": "ip",
"label": "203.0.113.42",
"attrs": {"network": "203.0.113.0/24"},
},
)
assert created.status_code == 400
case = Case.open(cid)
legacy = case.add_entity(
"ip", "203.0.113.43", {"network": "Old free text"}, by="user"
)
kept = client.patch(
f"/api/cases/{cid}/entities/{legacy['id']}",
json={"attrs": {"network": "Old free text", "provider": "Example"}},
)
changed = client.patch(
f"/api/cases/{cid}/entities/{legacy['id']}",
json={"attrs": {"network": "New free text"}},
)
assert kept.status_code == 200
assert changed.status_code == 400
def test_a_field_that_opens_a_subject_says_what_heads_it(client):
"""A place's four precision fields are all about how tightly the point is pinned,
which is worth saying once above them; its other names come first, bare, because
they are not. A vessel's registration numbers are just its own fields, so they
head nothing — and the panel renders them bare.
The heading is on the field rather than on the type because one type can hold two
subjects: a Claim says *what* it states, *when* it applies and *why* that is
believed, and running them all under one word would file a count as reasoning."""
rows = {row["type"]: row for row in client.get("/api/cases/entity-types").json()}
heads = {attr["key"]: attr["group"] for attr in rows["place"]["attrs"]}
assert heads == {
"aliases": "", "radius_m": "How precise", "footprint": "", "verbatim": "", "method": "",
}
assert [attr["key"] for attr in rows["place"]["attrs"]][:2] == ["aliases", "radius_m"]
assert {attr["group"] for attr in rows["vessel"]["attrs"]} == {""}
assert [attr["group"] for attr in rows["claim"]["attrs"]] == [
"What it states", "", "When", "", "", "Reasoning", "", "",
]
def test_a_heading_opens_its_block_once():
"""A field with no group of its own continues whatever heading is open, which is
how a place states "How precise" once over four fields. What that costs is order:
reopening an earlier heading further down the list would draw it twice, so each
one may be opened once."""
for entry in entities.ENTITY_TYPES:
opened = [attr.group for attr in entry.attrs if attr.group]
assert len(opened) == len(set(opened)), (entry.type, opened)
def test_a_heading_reads_as_a_heading_not_as_a_clause():
"""Same rule the relation groups follow: it labels a block rather than
completing a label, so it opens upper-case and does not run to a sentence."""
headings = {attr.group for e in entities.ENTITY_TYPES for attr in e.attrs if attr.group}
assert headings
for group in headings:
assert group == group.strip() and group[0].isupper(), group
assert not group.endswith("."), group
assert len(group) <= 24, group
def test_the_types_saved_through_a_tool_route_declare_no_fields():
"""A cross-layer gate. Details saves a `capture` through `/satellite` and a
`media` through `/media`, and those routes write the sidecar with a title and
notes only — a declared field on either type would be typed into the panel and
silently dropped on Save. Declaring one means teaching that branch to patch the
entity too; this test is what says so out loud instead of losing the value."""
for type_ in ("capture", "media"):
entry = entities.entity_type(type_)
assert entry is not None and not entry.attrs, type_
def test_only_hand_made_types_are_offered_for_creation(client):
rows = {row["type"]: row for row in client.get("/api/cases/entity-types").json()}
# a media is born from an import and a proof from an export, so neither
# belongs in a create menu
assert rows["media"]["manual"] is False
assert rows["proof"]["manual"] is False
assert rows["place"]["manual"] is False
assert rows["structure"]["manual"] is True
def test_every_declared_type_sits_in_a_declared_family():
assert {entry.family for entry in entities.ENTITY_TYPES} <= set(entities.FAMILIES)
# and every family earns its place: an empty one is a verb nobody can use
for family in entities.FAMILIES:
assert entities.types_in(family), family
def test_every_declared_type_says_what_it_is_for_when_the_case_is_drawn():
"""The role is the axis a graph lens narrows nodes on, and it has no default: a
type that did not decide would answer "is a picture of the case about this?" by
omission. Every role earns its place too — an empty one is a treatment nothing
receives."""
assert {entry.role for entry in entities.ENTITY_TYPES} == set(entities.ROLES)
for role in entities.ROLES:
assert entities.types_with_role(role), role
ONTOLOGY = Path(__file__).resolve().parent.parent / "docs" / "ONTOLOGY.md"
def _doc_table(text: str, header: str) -> list[list[str]]:
"""The body rows of the Markdown table under `header`, cells unquoted."""
lines = text.splitlines()
start = lines.index(header) + 2 # past the header and its |---| rule
rows = []
for line in lines[start:]:
if not line.startswith("|"):
break
rows.append([cell.strip().replace("`", "") for cell in line.strip("|").split("|")])
return rows
def _members(rows: list[list[str]]) -> dict[str, str]:
return {member.strip(): row[0] for row in rows for member in row[2].split(",")}
def test_the_filing_contract_lists_every_type_where_the_code_files_it():
"""ONTOLOGY.md is the contract a new tool files against, so a type the code
declares and the document leaves out is one nobody learns the rules of."""
text = ONTOLOGY.read_text(encoding="utf-8")
families = _members(_doc_table(text, "| Family | Reads as | Members |"))
roles = _members(_doc_table(text, "| Role | Reads as | Members | In the drawing |"))
registry = {
row[0]: (row[1], row[2])
for row in _doc_table(
text,
"| Type | Family | Role | State | Produced by | Key `attrs` | File-backed |",
)
}
for entry in entities.ENTITY_TYPES:
assert families.get(entry.type) == entry.family, entry.type
assert roles.get(entry.type) == entry.role, entry.type
assert registry.get(entry.type) == (entry.family, entry.role), entry.type
def test_a_type_is_shown_by_the_name_its_tool_gives_it(client):
"""The type id is storage and keeps its old word; the label is what Board, Files,
Details and Trash print, so it follows the tool: Inspect keeps one work per file,
Detect reruns a routine, and the areas serve Detect, not Compare."""
rows = {row["type"]: row for row in client.get("/api/cases/entity-types").json()}
assert rows["inspect-session"]["label"] == "Inspect work"
assert rows["analysis-follow-up"]["label"] == "Detect routine"
assert "Detect" in rows["analysis-zones"]["hint"]
for row in rows.values():
assert "session" not in row["label"].lower() or row["type"] == "compare-session"
assert "watch" not in row["label"].lower(), row["type"]
for type_ in ("analysis-zones", "analysis-area", "analysis-follow-up", "analysis-run"):
assert "Compare" not in rows[type_]["hint"], type_
def test_the_filing_contract_states_the_schemas_the_code_writes():
text = " ".join(ONTOLOGY.read_text(encoding="utf-8").split())
assert f"**Storage schema: `{CASE_SCHEMA}`.**" in text
assert f'{{"azimut": {{"schema": {CASE_SCHEMA},' in text
assert f"The internal SQLite schema is at version {SQLITE_SCHEMA}:" in text
def test_the_role_is_not_the_manual_flag_under_another_name():
"""The two axes are independent, which is why an existing field could not be
reused: `media` and `place` are tool-born subjects, `post` is tool-born and a
deliverable, `claim` is hand-made and a subject."""
roles = {entry.type: (entry.role, entry.manual) for entry in entities.ENTITY_TYPES}
assert roles["media"] == (entities.SUBJECT, False)
assert roles["place"] == (entities.SUBJECT, False)
assert roles["post"] == (entities.DELIVERABLE, False)
assert roles["claim"] == (entities.SUBJECT, True)
def test_every_declared_field_uses_a_known_editor():
for entry in entities.ENTITY_TYPES:
for attr in entry.attrs:
assert attr.kind in entities.ATTR_KINDS, (entry.type, attr.key)
def test_a_field_that_holds_sentences_says_so():
"""A quoted source and the reasoning behind a claim run to paragraphs, and the
form has no other way to know a field wants more than a line."""
for type_, key in (("claim", "method"), ("claim", "verbatim"),
("place", "method"), ("place", "verbatim")):
entry = entities.entity_type(type_)
attr = next(a for a in entry.attrs if a.key == key)
assert attr.kind == "longtext", (type_, key)
# and it is checked exactly as text is: same value, same bound
entities.check_attrs("claim", {"method": "x" * entities.MAX_TEXT})
with pytest.raises(CaseError):
entities.check_attrs("claim", {"method": "x" * (entities.MAX_TEXT + 1)})
with pytest.raises(CaseError):
entities.check_attrs("claim", {"verbatim": 12})
def test_no_two_declared_types_share_an_icon():
"""The icon is the whole of what tells two rows apart at a glance. A lorry, a
freighter and an airframe drawn as one symbol made a mixed list unreadable.
Every declared type, not just the ones an analyst creates: the board lists a
case whole, so a tool-born type sits in the same column as a hand-made one. That
is how a bookmark and a domain both drew a globe.
"""
icons = [entry.icon for entry in entities.ENTITY_TYPES]
assert len(icons) == len(set(icons)), sorted(icons)
def test_a_closed_field_declares_the_whole_of_what_it_may_hold():
"""`choice` is the only kind whose validity is a list rather than a shape, so the
list has to exist and has to be the only thing carrying one. A choice with no
options renders as an empty dropdown; options on a text field are a scale the
validator would never apply."""
for entry in entities.ENTITY_TYPES:
for attr in entry.attrs:
if attr.kind == "choice":
assert attr.options, (entry.type, attr.key)
else:
assert not attr.options, (entry.type, attr.key)
def test_every_declared_type_says_what_it_owns_on_disk():
"""The registry-level twin of the full-case drift gate: a type cannot join the
vocabulary without deciding whether it is file-backed."""
undeclared = {e.type for e in entities.ENTITY_TYPES if not artifacts.declares(e.type)}
assert undeclared == set()
def test_a_retired_type_leaves_nothing_behind():
"""`alias` folded into `account` with an optional platform, and `event` was
replaced by the claim node. Neither was ever created by a tool, so the entries
that used to describe them are dead wiring."""
assert "alias" not in artifacts.NO_FILES
assert "event" not in artifacts.NO_FILES
assert entities.entity_type("alias") is None
assert entities.entity_type("event") is None
def test_an_undeclared_free_type_has_no_family():
"""Free-string types stay storable. What they cannot be is the end of a
relation, since nothing states what they may join."""
assert entities.family_of("cuneiform-tablet") is None
assert entities.entity_type("cuneiform-tablet") is None
# -- the verbs declare their exact endpoints ----------------------------------
def test_a_new_type_inherits_only_the_family_wide_relations(
client, monkeypatch
):
"""Broad verbs follow a family; narrowed verbs still need an explicit type."""
invented = entities.EntityType(
"drone", "Drone", entities.ASSET, "grip", entities.SUBJECT, manual=True
)
monkeypatch.setattr(entities, "ENTITY_TYPES", entities.ENTITY_TYPES + (invented,))
cid = _new_case(client, "Inherited verbs")
case = Case.open(cid)
person = case.add_entity("person", "Owner", {}, by="user")
drone = case.add_entity("drone", "Quadcopter", {}, by="user")
media = case.add_entity("media", "Clip", {"path": "media/clip.mp4"}, by="user")
place = case.add_entity("place", "Field", {"lat": 1.0, "lon": 2.0}, by="user")
assert _link(client, cid, person["id"], drone["id"], "owns").status_code == 200
assert _link(client, cid, drone["id"], media["id"], "appears-in").status_code == 200
assert _link(client, cid, drone["id"], place["id"], "sited-at").status_code == 400
def test_the_shipped_relations_keep_the_endpoints_they_shipped_with():
"""The material family *is* the old {media, capture} pair, and generalising to
families must never have widened these three by itself.
`depicts` gained `proof` since, and that one is a decision rather than a side
effect: a proof is a rendered image, so what it shows is a property of its
pixels, and it is where a geolocation is concluded (ONTOLOGY §3). The line the
guard still holds is the one below it — **`located-at` stays material-only**,
because a proof was composed, never recorded anywhere.
"""
by_type = {entry.type: entry for entry in link_engine.RELATION_TYPES}
assert by_type["located-at"].from_types == frozenset({"media"})
assert by_type["located-at"].to_types == frozenset({"place"})
assert by_type["depicts"].from_types == frozenset({"media", "capture", "proof"})
assert by_type["depicts"].to_types == frozenset({"place"})
assert by_type["same-image-as"].from_types == frozenset({"media"})
assert by_type["same-image-as"].to_types == frozenset({"media"})
def test_the_new_verbs_keep_the_approved_endpoint_matrix():
by_type = {entry.type: entry for entry in link_engine.RELATION_TYPES}
assert by_type["owns"].from_types == entities.types_in(entities.ACTOR)
assert by_type["owns"].to_types == frozenset({
"organization", "vehicle", "vessel", "aircraft", "structure",
"account", "email", "phone", "domain", "ip", "network",
})
assert by_type["posted"].from_types == frozenset({"account"})
assert by_type["posted"].to_types == frozenset({"media", "bookmark"})
assert by_type["appears-in"].from_types == entities.types_in(
entities.ACTOR, entities.ASSET, entities.IDENTIFIER
)
assert by_type["appears-in"].to_types == frozenset({"media", "capture"})
assert by_type["sited-at"].from_types == frozenset({"structure"})
assert by_type["sited-at"].to_types == frozenset({"place"})
assert by_type["part-of"].from_types == frozenset({"organization"})
assert by_type["part-of"].to_types == frozenset({"organization"})
assert by_type["member-of"].from_types == frozenset({"person", "organization"})
assert by_type["member-of"].to_types == frozenset({"organization"})
assert by_type["in-network"].from_types == frozenset({"ip", "network"})
assert by_type["in-network"].to_types == frozenset({"network"})
assert by_type["instance-of"].from_types == entities.types_in(entities.ASSET)
assert by_type["instance-of"].to_types == frozenset({"equipment-type"})
assert "equipment-type" in by_type["about"].to_types
# -- which verbs a pair of types has at all ------------------------------------
def test_a_pair_offers_only_the_verbs_the_registry_allows():
"""`pair_verbs` is the type-only endpoint check, asked before either entity exists.
Two ordered pairs, two different answers: a media may be *at* a place or *show*
one, and a person may only be a member of an organization, own it, or be tied to
it. `part-of` is absent on purpose — it runs organization to organization, so a
person is never *part of* one.
"""
assert [s.type for s in link_engine.pair_verbs("media", "place")] == [
"located-at", "depicts",
]
assert [s.type for s in link_engine.pair_verbs("person", "organization")] == [
"owns", "member-of", "associated-with",
]
assert [s.type for s in link_engine.pair_verbs("organization", "organization")] == [
"owns", "part-of", "member-of", "associated-with",
]
assert [s.type for s in link_engine.pair_verbs("structure", "place")] == ["sited-at"]
def test_a_person_and_a_point_have_no_verb_between_them():
"""The witness case for a promotion that maps coordinates onto a column of people:
the vocabulary joins them by nothing, so the pair is never offered and a latitude
never lands on a person as a field nothing shows or edits."""
assert link_engine.pair_verbs("person", "place") == ()
assert link_engine.pair_verbs("place", "media") == ()
def test_a_pair_never_offers_what_only_a_machine_may_state():
"""`same-image-as` is enrichment's own claim and the derivation chain is recorded
by the save that produced it, so neither is a verb a batch of edges may pick."""
assert link_engine.pair_verbs("media", "media") == ()
offered = {
spec.type
for a in ("media", "person", "organization", "note", "proof")
for b in ("media", "person", "organization", "place")
for spec in link_engine.pair_verbs(a, b)
}
assert offered.isdisjoint({"same-image-as", *link_engine.CHAIN_TYPES})
def test_a_pair_can_be_asked_for_one_kind_of_gesture():
"""A document naming a place is a pointer, not a finding, and the two never share a
select — so the caller asks for the action it is drawing."""
assert [s.type for s in link_engine.pair_verbs("note", "place")] == ["mentions"]
assert link_engine.pair_verbs("note", "place", action="relation") == ()
assert [
s.type for s in link_engine.pair_verbs("note", "place", action="mention")
] == ["mentions"]
# -- what state a thing is in, and how many of it ------------------------------
def test_every_asset_says_what_state_it_is_in(client):
"""A bridge, a ship, an airframe and a lorry can all be damaged, so the field is
the family's rather than the two types it was first wanted for. One list, because
a count that groups by condition has to reach both the asset and the claim."""
rows = {row["type"]: row for row in client.get("/api/cases/entity-types").json()}
for type_ in entities.types_in(entities.ASSET):
field = next(a for a in rows[type_]["attrs"] if a["key"] == "condition")
assert field["kind"] == "choice"
assert [o["value"] for o in field["options"]] == [
"intact", "damaged", "destroyed", "abandoned",
]
claim_condition = next(a for a in rows["claim"]["attrs"] if a["key"] == "condition")
assert claim_condition["options"] == field["options"]
def test_changing_hands_is_not_a_condition():
""""Captured" is a change of owner, which `owns` already states. Folded into the
scale it would mix condition with possession, and a mixture does not aggregate."""
stored = {value for value, _ in entities.ASSET_CONDITIONS}
assert "captured" not in stored
assert "seized" not in stored
def test_a_condition_outside_the_scale_is_refused(client):
cid = _new_case(client, "Condition scale")
good = client.post(
f"/api/cases/{cid}/entities",
json={"type": "structure", "label": "Rail bridge", "attrs": {"condition": "destroyed"}},
)
invented = client.post(
f"/api/cases/{cid}/entities",
json={"type": "structure", "label": "Road bridge", "attrs": {"condition": "scratched"}},
)
# absent is unknown, and an analyst is entitled to go back to it
cleared = client.patch(
f"/api/cases/{cid}/entities/{good.json()['id']}",
json={"attrs": {"condition": None}},
)
assert good.status_code == 200, good.text
assert invented.status_code == 400
assert cleared.status_code == 200
assert cleared.json()["attrs"].get("condition") in (None, "")
def test_a_count_is_a_whole_number_of_at_least_one(client):
"""Zero is not a count for the same reason zero is not a radius: absent already
says "seen, not counted", and half a destroyed tank is not a quantity anyone can
defend."""
cid = _new_case(client, "Counting")
def claim(attrs):
return client.post(
f"/api/cases/{cid}/entities",
json={"type": "claim", "label": "Two of these", "attrs": attrs},
)
assert claim({"count": 2}).status_code == 200
assert claim({"count": 2.0}).status_code == 200 # JSON has one number type
assert claim({"count": 0}).status_code == 400
assert claim({"count": -3}).status_code == 400
assert claim({"count": 2.5}).status_code == 400
assert claim({"count": True}).status_code == 400
assert claim({"count": entities.MAX_COUNT + 1}).status_code == 400
# absent is "seen, not counted", which is a different answer from one
assert claim({}).status_code == 200
def test_a_count_says_it_steps_by_one(client):
"""Served so the spinner and the validator cannot disagree about what a valid
quantity is."""
rows = {row["type"]: row for row in client.get("/api/cases/entity-types").json()}
count = next(a for a in rows["claim"]["attrs"] if a["key"] == "count")
radius = next(a for a in rows["place"]["attrs"] if a["key"] == "radius_m")
assert count["whole"] is True
assert count["minimum"] == 1
assert radius["whole"] is False # a metre is not the smallest honest step
def test_a_claim_declares_when_its_statement_applies(client):
rows = {row["type"]: row for row in client.get("/api/cases/entity-types").json()}
fields = {field["key"]: field for field in rows["claim"]["attrs"]}
assert fields["when"]["kind"] == "temporal"
assert fields["when"]["group"] == "When"
assert fields["time_role"]["kind"] == "choice"
assert [option["value"] for option in fields["time_role"]["options"]] == [
"occurred", "observed", "valid",
]
def test_a_claim_keeps_only_supported_temporal_values(client):
cid = _new_case(client, "Temporal statement")
created = client.post(
f"/api/cases/{cid}/entities",
json={
"type": "claim",
"label": "The address appeared in the access log",
"attrs": {
"when": "2026-08-11T18:40:00+02:00",
"time_role": "observed",
},
},
)
assert created.status_code == 200, created.text
assert created.json()["attrs"]["when"] == "2026-08-11T18:40:00+02:00"
interval = client.patch(
f"/api/cases/{cid}/entities/{created.json()['id']}",
json={"attrs": {"when": "2026-08~/2026-10?", "time_role": "valid"}},
)
bad_date = client.patch(
f"/api/cases/{cid}/entities/{created.json()['id']}",
json={"attrs": {"when": "2026-02-29"}},
)
bad_role = client.patch(
f"/api/cases/{cid}/entities/{created.json()['id']}",
json={"attrs": {"time_role": "published"}},
)
assert interval.status_code == 200, interval.text
assert interval.json()["attrs"]["when"] == "2026-08~/2026-10?"
assert bad_date.status_code == 400
assert bad_role.status_code == 400
def test_a_claim_may_keep_a_local_time_or_no_time_at_all(client):
cid = _new_case(client, "Local time statement")
local = client.post(
f"/api/cases/{cid}/entities",
json={
"type": "claim",
"label": "The camera clock showed this time",
"attrs": {"when": "2026-08-11T18:40:00"},
},
)
undated = client.post(
f"/api/cases/{cid}/entities",
json={"type": "claim", "label": "The date is not known", "attrs": {}},
)
cleared = client.patch(
f"/api/cases/{cid}/entities/{local.json()['id']}",
json={"attrs": {"when": None}},
)
assert local.status_code == 200, local.text
assert undated.status_code == 200, undated.text
assert cleared.status_code == 200, cleared.text
def test_a_claim_states_the_zone_its_date_was_read_in(client):
"""A day stated in Kyiv is Kyiv's day: the Timeline bounds it from that zone's
midnights, and a zone this install cannot load is refused rather than stored."""
cid = _new_case(client, "Zoned statement")
created = client.post(
f"/api/cases/{cid}/entities",
json={
"type": "claim",
"label": "The strike was filmed",
"attrs": {"when": "2024-03-12", "when_zone": "Europe/Kyiv"},
},
)
bad_zone = client.patch(
f"/api/cases/{cid}/entities/{created.json()['id']}",
json={"attrs": {"when_zone": "Mars/Olympus"}},
)
rows = client.get(
f"/api/cases/{cid}/timeline",
params={"entity": created.json()["id"], "category": "statement", "include_undated": "true"},
).json()["items"]
assert created.status_code == 200, created.text
assert bad_zone.status_code == 400
assert [(row["earliest"], row["latest"], row["tz"]) for row in rows] == [
("2024-03-11T22:00:00.000000Z", "2024-03-12T22:00:00.000000Z", "Europe/Kyiv"),
]
# -- the class family ----------------------------------------------------------
def test_a_model_is_its_own_family_and_not_an_asset(client):
"""Nobody owns "T-72B3" and it sits nowhere, so the three verbs an asset takes
are all wrong for it. Held in `asset` the picker would offer them."""
rows = {row["type"]: row for row in client.get("/api/cases/entity-types").json()}
by_type = {entry.type: entry for entry in link_engine.RELATION_TYPES}
assert rows["equipment-type"]["family"] == "class"
assert entities.types_in(entities.CLASS) == frozenset({"equipment-type"})
for verb in ("owns", "appears-in", "sited-at"):
assert "equipment-type" not in by_type[verb].to_types, verb
assert "equipment-type" not in by_type[verb].from_types, verb
def test_a_named_object_states_which_model_it_is(client):
cid = _new_case(client, "Order of battle kit")
case = Case.open(cid)
tank = case.add_entity("vehicle", "Turret 214", {"plate": "214"}, by="user")
model = case.add_entity("equipment-type", "T-72B3", {"category": "tank"}, by="user")
crew = case.add_entity("person", "Crew commander", {}, by="user")
stated = _link(client, cid, tank["id"], model["id"], "instance-of")
assert stated.status_code == 200, stated.text
# and it runs one way: a model is not an instance of the object
assert _link(client, cid, model["id"], tank["id"], "instance-of").status_code == 400
# a person is not a member of a class either
assert _link(client, cid, crew["id"], model["id"], "instance-of").status_code == 400
# "probably a T-72B3" is a reading of the footage, so the edge takes a rating
assert link_engine.relation_type("instance-of").ratable is True
def test_a_statement_counts_a_model_rather_than_minting_anonymous_objects(client):
"""The whole point of the class family: "two of these were destroyed here" with
no second vehicle entity that names nobody."""
cid = _new_case(client, "Counted losses")
case = Case.open(cid)
model = case.add_entity("equipment-type", "ZU-23-2", {"category": "air defence"}, by="user")
place = case.add_entity("place", "Crossroads", {"lat": 48.1, "lon": 37.6}, by="user")
video = case.add_entity("media", "Drone clip", {"path": "media/clip.mp4"}, by="user")
claim = case.add_entity(
"claim", "Two ZU-23-2 destroyed at the crossroads",
{"count": 2, "condition": "destroyed", "confidence": "probable"}, by="user",
)
for to_id, verb in ((model["id"], "about"), (place["id"], "at"), (video["id"], "cites")):
stated = _link(client, cid, claim["id"], to_id, verb)
assert stated.status_code == 200, f"{verb}: {stated.text}"
assert {link["type"] for link in case.links_of(claim["id"])} == {"about", "at", "cites"}
assert case.get_entity(claim["id"])["attrs"]["count"] == 2
# the count sits on the node, never on the connector it points through
assert all(link.get("confidence") is None for link in case.links_of(claim["id"]))
def test_each_entity_type_declares_every_field_once():
for entry in entities.ENTITY_TYPES:
keys = [attr.key for attr in entry.attrs]
assert len(keys) == len(set(keys)), f"duplicate field on {entry.type}: {keys}"
def test_mentions_are_a_separate_action_from_relations(client):
rows = {row["type"]: row for row in client.get("/api/cases/relation-types").json()}
assert rows["mentions"]["action"] == "mention"
assert rows["mentions"]["group"] == "Mentions"
assert rows["mentions"]["ratable"] is False
assert {type_ for type_, row in rows.items() if row["action"] == "claim"} == {
"about", "at", "cites", "contradicts"
}
assert rows["owns"]["ratable"] is True
def test_a_quick_claim_seats_each_type_the_way_its_form_expects(client):
"""The quick claim form seats the entity it is filed from on the first of
`at`, `cites`, `about` that takes it (`frontend/src/lib/quickClaim.js`, whose
test copies these answers). Pinned here so a verb table change that would move
a place off `at` or a video off `cites` fails where the table lives."""
rows = {row["type"]: row for row in client.get("/api/cases/relation-types").json()}
def seats(type_):
return {verb for verb in ("about", "at", "cites") if type_ in rows[verb]["to_types"]}
assert seats("equipment-type") == {"about"}
assert seats("vehicle") == {"about"}
assert seats("person") == {"about"}
assert seats("account") == {"about"}
assert seats("place") == {"about", "at"}
assert seats("media") == {"about", "cites"}
assert seats("proof") == {"cites"}
assert seats("claim") == {"cites"}
assert seats("post") == set()
def test_an_order_of_battle_is_part_of_edges_between_organizations(client):
"""The tree an OSINT conflict case is built on: a battalion inside a brigade
inside a corps. `owns` would read wrong — a brigade commands its battalions
rather than owning them — so containment is its own verb."""
cid = _new_case(client, "Order of battle")
case = Case.open(cid)
corps = case.add_entity("organization", "3rd Army Corps", {"echelon": "corps"}, by="user")
brigade = case.add_entity(
"organization", "72nd Motor Rifle Brigade", {"echelon": "brigade"}, by="user"
)
battalion = case.add_entity(
"organization", "1st Battalion", {"echelon": "battalion"}, by="user"
)
truck = case.add_entity("vehicle", "Ural-4320", {"plate": "AB 1234"}, by="user")
commander = case.add_entity("person", "Unit commander", {}, by="user")
assert _link(client, cid, battalion["id"], brigade["id"], "part-of").status_code == 200
assert _link(client, cid, brigade["id"], corps["id"], "part-of").status_code == 200
# the unit's kit is owned, never a part of it
assert _link(client, cid, brigade["id"], truck["id"], "owns").status_code == 200
assert _link(client, cid, commander["id"], brigade["id"], "member-of").status_code == 200
assert _link(client, cid, truck["id"], brigade["id"], "part-of").status_code == 400
assert _link(client, cid, brigade["id"], truck["id"], "part-of").status_code == 400
# containment never cascades: disbanding a brigade does not delete its corps
case.remove_entity(brigade["id"])
assert case.get_entity(corps["id"]) is not None
assert case.get_entity(battalion["id"]) is not None
def test_a_narrowing_can_only_remove_never_widen():
"""`from_only` intersects its families rather than replacing them, so a
narrowing cannot smuggle in a type from somewhere else."""
rogue = link_engine.RelationType(
"rogue",
"reaches for",
from_families=frozenset({entities.PLACE}),
to_families=frozenset({entities.PLACE}),
from_only=frozenset({"person"}),
)
assert rogue.from_types == frozenset()
# -- what the vocabulary refuses ----------------------------------------------
def test_the_new_verbs_refuse_the_pairs_that_read_backwards(client):
cid = _new_case(client, "Refused new verbs")
case = Case.open(cid)
person = case.add_entity("person", "Owner", {}, by="user")
vessel = case.add_entity("vessel", "Bulk carrier", {"imo": "9074729"}, by="user")
account = case.add_entity("account", "@harbourwatch", {}, by="user")
media = case.add_entity("media", "Clip", {"path": "media/clip.mp4"}, by="user")
place = case.add_entity("place", "Quay", {"lat": 1.0, "lon": 2.0}, by="user")
# an asset does not own its owner
assert _link(client, cid, vessel["id"], person["id"], "owns").status_code == 400
# a person does not post; the account they own does
assert _link(client, cid, person["id"], media["id"], "posted").status_code == 400
# a place is not somewhere a vessel appears
assert _link(client, cid, vessel["id"], place["id"], "appears-in").status_code == 400
# an identifier is not sited anywhere
assert _link(client, cid, account["id"], place["id"], "sited-at").status_code == 400
assert case.links_of(person["id"]) == []
def test_an_undeclared_type_cannot_be_related(client):
"""Storable, but not relatable: nothing in the vocabulary says what a free type
may join, so the API refuses rather than guessing."""
cid = _new_case(client, "Free type")
case = Case.open(cid)
tablet = case.add_entity("cuneiform-tablet", "Tablet 4", {}, by="user")
place = case.add_entity("place", "Dig site", {"lat": 1.0, "lon": 2.0}, by="user")
assert _link(client, cid, tablet["id"], place["id"], "sited-at").status_code == 400
assert case.get_entity(tablet["id"]) is not None
def test_an_analyst_can_own_a_vessel_and_place_a_building(client):
"""The vocabulary end to end: the two statements the new types exist for."""
cid = _new_case(client, "Harbour survey")
case = Case.open(cid)
company = case.add_entity("organization", "Northwind Shipping", {}, by="user")
vessel = case.add_entity("vessel", "MV Aurora", {"imo": "9074729"}, by="user")
warehouse = case.add_entity("structure", "Quay 4 warehouse", {"kind": "warehouse"}, by="user")
place = case.add_entity("place", "Quay 4", {"lat": 53.44, "lon": 14.55}, by="user")
owned = _link(client, cid, company["id"], vessel["id"], "owns")
sited = _link(client, cid, warehouse["id"], place["id"], "sited-at")
assert owned.status_code == 200, owned.text
assert sited.status_code == 200, sited.text
# stated by hand, so confirmed: there is nothing left to review
assert owned.json()["provenance"]["status"] == "confirmed"
assert {link["type"] for link in case.links_of(vessel["id"])} == {"owns"}
def test_the_vocabulary_explains_itself_in_one_clause():
"""The words are terse by design — `capture`, `claim`, `collected` — and a terse
word nobody can look up is jargon. Every type and every family says what it is,
and each says it the way the copy rules ask: one clause, no full stop, nothing
that grows into a paragraph in a tooltip."""
readings = [entry.hint for entry in entities.ENTITY_TYPES]
readings += list(entities.FAMILY_READS.values())
readings += [r.hint for r in link_engine.RELATION_TYPES]
readings += [hint for _, _, hint in link_engine.CONFIDENCE_LEVELS]
readings += [a.hint for e in entities.ENTITY_TYPES for a in e.attrs if a.hint]
assert readings, "nothing declares a reading"
for hint in readings:
assert hint, readings
assert not hint.endswith("."), hint # a clause, not a sentence
assert "—" not in hint, hint # no em-dash appositive
assert len(hint) <= 100, hint
assert hint[0].islower(), hint # it completes a label, it does not open one
def test_every_family_and_verb_is_explained(client):
"""A reading nobody serves is a reading nobody reads, and a family the menu names
without explaining is the jargon this exists to remove."""
assert set(entities.FAMILY_READS) == set(entities.FAMILIES)
for entry in link_engine.RELATION_TYPES:
assert entry.hint, entry.type
rows = client.get("/api/cases/entity-types").json()
assert all(row["hint"] and row["family_reads"] for row in rows)
verbs = client.get("/api/cases/relation-types").json()
assert all(row["hint"] for row in verbs)
levels = client.get("/api/cases/confidence-levels").json()
assert all(row["hint"] for row in levels)
def test_a_document_mentions_what_it_refers_to(client):
"""The verb that answers "this post is about that spot" without pretending the
post was made from it. It reaches `place` and `collected` as well as the subject
families, because a note about a point is the ordinary case and refusing it would
leave that expressible only as a claim."""
cid = _new_case(client, "Mentions")
case = Case.open(cid)
note = case.add_entity("note", "Field notes", {"path": "notes/field.md"}, by="user")
post = case.add_entity("post", "Thread", {"draft": ".drafts/t.json"}, by="user")
place = case.add_entity("place", "North quay", {"lat": 1.0, "lon": 2.0}, by="user")
photo = case.add_entity("media", "Frame", {"path": "media/f.jpg"}, by="user")
person = case.add_entity("person", "A driver", {}, by="user")
claim = case.add_entity("claim", "The driver used the quay", {}, by="user")
for from_id, to_id in (
(note["id"], place["id"]),
(note["id"], person["id"]),
(note["id"], post["id"]),
(note["id"], claim["id"]),
(post["id"], photo["id"]),
):
assert _link(client, cid, from_id, to_id, "mentions").status_code == 200
# and it runs one way: material is gathered, so it refers to nothing
assert _link(client, cid, photo["id"], place["id"], "mentions").status_code == 400
assert _link(client, cid, note["id"], note["id"], "mentions").status_code == 400
def test_a_pointer_is_headed_apart_from_the_findings(client):
"""`mentions` says a document names something; every other verb says something
about the world. Run together in one list the weaker one borrows the weight of
the others, so the registry heads it and every surface obeys — the split is
declared once, not drawn per screen."""
headed = {entry.type: entry.group for entry in link_engine.RELATION_TYPES if entry.group}
assert headed == {"mentions": "Mentions"}
for group in headed.values():
# a heading, not a clause: it labels a section rather than completing a label
assert group == group.strip() and group[0].isupper(), group
assert not group.endswith("."), group
assert len(group) <= 24, group
rows = {row["type"]: row for row in client.get("/api/cases/relation-types").json()}
assert rows["mentions"]["group"] == "Mentions"
assert rows["located-at"]["group"] == ""
def test_mentioning_is_not_being_made_from(client):
"""The two live side by side on the same pair and answer different questions: the
chain says the file was built from that, the mention says it merely talks about
it. Only the chain leaves a scar when the target goes."""
cid = _new_case(client, "Mention beside chain")
case = Case.open(cid)
proof = case.add_entity("proof", "Match", {"spec": "proofs/.meta/m.json"}, by="user")
capture = case.add_entity("capture", "Overview", {"path": "captures/o.png"}, by="user")
case.add_link(proof["id"], capture["id"], "derived-from", by="proof-composer")
assert _link(client, cid, proof["id"], capture["id"], "mentions").status_code == 200
kinds = {link["type"] for link in case.links_of(proof["id"])}
assert kinds == {"derived-from", "mentions"}
# deleting the source scars the proof once, for the derivation and not the mention
client.delete(f"/api/cases/{cid}/entities/{capture['id']}")
lost = case.get_entity(proof["id"])["attrs"].get("lost_sources", [])
assert len(lost) == 1
assert not case.links_of(proof["id"])
# -- when the case already holds the value ------------------------------------
@pytest.mark.parametrize(
"type_, one, other",
[
("account", "@Handle", "handle"),
("email", "[email protected]", "[email protected]"),
("phone", "+33 6 12 34 56 78", "+33-612.345678"),
("domain", "Example.org.", "example.org"),
("ip", "203.0.113.42", "203.0.113.42 "),
("network", "203.0.113.0/24", "203.0.113.0/24"),
],
)
def test_one_identifier_written_two_ways_is_one_identity(type_, one, other):
key = entities.identity_key(type_, one)
assert key and key == entities.identity_key(type_, other)
@pytest.mark.parametrize(
"type_, one, other",
[
# Supplying a country code is a guess about what the analyst meant.
("phone", "+33612345678", "0612345678"),
# A subdomain is its own hostname, not a spelling of the parent.
("domain", "www.example.org", "example.org"),
("email", "[email protected]", "[email protected]"),
],
)
def test_two_values_that_only_look_alike_stay_two_identities(type_, one, other):
assert entities.identity_key(type_, one) != entities.identity_key(type_, other)
def test_only_an_identifier_has_an_identity_a_label_can_duplicate():
"""Two people really can share a name, and two claims really can be worded alike.
The `identifier` family is the one place the label *is* the identity (ONTOLOGY
§2), so it is the only one that answers here — a guard over the rest would refuse
entities that are genuinely different.
"""
for entry in entities.ENTITY_TYPES:
answered = bool(entities.identity_key(entry.type, "Some value"))
assert answered == (entry.family == entities.IDENTIFIER), entry.type
assert entities.identity_key("email", " ") == ""
assert entities.identity_key("not-a-type", "anything") == ""
def test_the_case_says_which_row_already_holds_an_identifier(client):
"""It reports and never refuses: merging is not shipped, so a create that failed
would leave the analyst holding a value with nowhere to put it."""
cid = _new_case(client, "Twin identifiers")
case = Case.open(cid)
first = case.add_entity("account", "@osint_handle", {}, by="user")
person = case.add_entity("person", "A Name", {}, by="user")
def twin(type_, label, ignore=""):
return client.get(
f"/api/cases/{cid}/entities/twin",
params={"type": type_, "label": label, "ignore": ignore},
).json()["entity"]
# the sigil is how the same handle gets filed twice a week apart
assert twin("account", "osint_handle")["id"] == first["id"]
assert twin("account", " @OSINT_Handle ")["id"] == first["id"]
assert twin("account", "someone_else") is None
# an entity is never its own twin, which is what makes this usable on a rename
assert twin("account", "@osint_handle", ignore=first["id"]) is None
# two people may share a name, so the question is not asked of them
assert twin("person", "A Name") is None
assert person["id"]
# and the value really can still be filed: this warns, it does not block
again = client.post(
f"/api/cases/{cid}/entities",
json={"type": "account", "label": "osint_handle", "attrs": {}},
)
assert again.status_code == 200
@pytest.mark.parametrize("type_", ["person", "organization", "vessel", "structure", "place", "equipment-type"])
def test_a_subject_can_be_found_by_its_other_names(client, type_):
"""A ship renamed twice, a unit known by its acronym, a village with a name in
each language: the other names are a declared text field, so the search index
and `@` reach them without a migration."""
rows = {row["type"]: row for row in client.get("/api/cases/entity-types").json()}
alias = next(attr for attr in rows[type_]["attrs"] if attr["key"] == "aliases")
assert alias["kind"] == "text"
cid = client.post("/api/cases", json={"name": f"Aliases {type_}"}).json()["id"]
made = client.post(
f"/api/cases/{cid}/entities",
json={"type": type_, "label": "Plain name", "attrs": {"aliases": "Кі́ров; Άλφα, Nord Star"}},
)
assert made.status_code == 200, made.text
for term in ("кіров", "αλφα", "nord star"):
found = client.get(f"/api/cases/{cid}/catalog/entities", params={"q": term}).json()["items"]
assert [entity["id"] for entity in found] == [made.json()["id"]], term