agos-context 0.1.0__py3-none-any.whl

agos_context/compile.py

@@ -0,0 +1,363 @@
+"""Deterministic closure, bounds, and identity for context slices."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, cast
+
+from pydantic import AwareDatetime, TypeAdapter
+
+from agos_context.graph import (
+  Bounds,
+  Limits,
+  Link,
+  Node,
+  Omission,
+  Pin,
+  Policy,
+  Ref,
+  Slice,
+  canonical_json_bytes,
+  omission_key,
+  pin_key,
+  policy_key,
+  ref_key,
+  stable_hash,
+)
+
+_AWARE_DATETIME = TypeAdapter(AwareDatetime)
+
+
+@dataclass(frozen=True, slots=True)
+class SliceOrder:
+  """Complete retention order supplied by the purpose compiler."""
+
+  nodes: tuple[Pin, ...]
+  links: tuple[str, ...]
+
+
+def retention_order(
+  *,
+  roots: Sequence[Pin],
+  nodes: Sequence[Node],
+  links: Sequence[Link],
+) -> SliceOrder:
+  """Complete node order around already-prioritized roots and links."""
+
+  pins = {node.pin for node in nodes}
+  pin_by_ref: dict[Ref, Pin] = {}
+  for pin in pins:
+    current = pin_by_ref.get(pin.ref)
+    if current is not None and current != pin:
+      raise ValueError("context_slice_node_ref_ambiguous")
+    pin_by_ref[pin.ref] = pin
+
+  ordered: list[Pin] = []
+  seen: set[Pin] = set()
+
+  def add(pin: Pin) -> None:
+    if pin in pins and pin not in seen:
+      ordered.append(pin)
+      seen.add(pin)
+
+  for pin in roots:
+    add(pin)
+  for row in links:
+    add(row.owner)
+    for ref in (row.source, row.target):
+      candidate = pin_by_ref.get(ref)
+      if candidate is not None:
+        add(candidate)
+  for pin in sorted(pins, key=pin_key):
+    add(pin)
+  return SliceOrder(
+    nodes=tuple(ordered),
+    links=tuple(dict.fromkeys(row.id for row in links)),
+  )
+
+
+def compile_slice(
+  *,
+  purpose: str,
+  roots: Sequence[Ref],
+  effective_as_of: AwareDatetime,
+  observed_before: AwareDatetime,
+  nodes: Sequence[Node],
+  order: SliceOrder,
+  links: Sequence[Link] = (),
+  omissions: Sequence[Omission] = (),
+  policies: Sequence[Policy],
+  limits: Limits | None = None,
+) -> Slice:
+  """Compile already-authorized owner contributions without adding authority."""
+
+  selected_limits = Limits.model_validate(limits or Limits())
+  canonical_roots = tuple(sorted(set(roots), key=ref_key))
+  canonical_nodes = _nodes(nodes)
+  canonical_links = _links(links)
+  canonical_policies = _policies(policies)
+  source_omissions = list(_omissions(omissions))
+  effective_as_of = _AWARE_DATETIME.validate_python(effective_as_of)
+  observed_before = _AWARE_DATETIME.validate_python(observed_before)
+  nodes_by_ref = _nodes_by_ref(canonical_nodes)
+  if (
+    not canonical_roots
+    or any(root not in nodes_by_ref for root in canonical_roots)
+  ):
+    raise ValueError("context_slice_root_missing_or_ambiguous")
+  pins = {node.pin for node in canonical_nodes}
+  refs = set(nodes_by_ref)
+  for row in canonical_links:
+    if row.owner not in pins:
+      raise ValueError("context_slice_link_owner_missing")
+    if row.source not in refs or row.target not in refs:
+      raise ValueError("context_slice_link_ref_missing")
+
+  ordered_nodes = _ordered_nodes(canonical_nodes, order.nodes)
+  ordered_links = _ordered_links(canonical_links, order.links)
+  retained_links = list(ordered_links[:selected_limits.max_links])
+  count_link_drops = len(canonical_links) - len(retained_links)
+  required = _required(canonical_roots, retained_links, nodes_by_ref)
+  while len(required) > selected_limits.max_nodes and retained_links:
+    retained_links.pop()
+    count_link_drops += 1
+    required = _required(canonical_roots, retained_links, nodes_by_ref)
+  if len(required) > selected_limits.max_nodes:
+    raise ValueError("context_slice_root_limit")
+
+  optional = [
+    node
+    for node in ordered_nodes
+    if node.pin not in required
+  ]
+  retained_nodes = (
+    [node for node in ordered_nodes if node.pin in required]
+    + optional[:selected_limits.max_nodes - len(required)]
+  )
+  count_node_drops = len(canonical_nodes) - len(retained_nodes)
+  byte_drops = 0
+
+  while True:
+    generated = _limit_omissions(
+      source_omissions
+      + _generated_omissions(
+        nodes=count_node_drops,
+        links=count_link_drops,
+        byte_count=byte_drops,
+      ),
+      selected_limits.max_omissions,
+    )
+    payload = _payload(
+      purpose=purpose,
+      roots=canonical_roots,
+      effective_as_of=effective_as_of,
+      observed_before=observed_before,
+      nodes=retained_nodes,
+      links=retained_links,
+      omissions=generated,
+      policies=canonical_policies,
+      limits=selected_limits,
+    )
+    if payload["bounds"]["content_bytes"] <= selected_limits.max_bytes:
+      return Slice.model_validate(payload)
+
+    retained_by_ref = _nodes_by_ref(retained_nodes)
+    referenced = _required(canonical_roots, retained_links, retained_by_ref)
+    optional_pins = [
+      node.pin
+      for node in retained_nodes
+      if node.pin not in referenced
+    ]
+    if optional_pins:
+      removed = optional_pins[-1]
+      retained_nodes = [node for node in retained_nodes if node.pin != removed]
+    elif retained_links:
+      retained_links.pop()
+    elif source_omissions:
+      source_omissions.pop()
+    else:
+      raise ValueError("context_slice_byte_limit")
+    byte_drops += 1
+
+
+def _nodes(values: Sequence[Node]) -> tuple[Node, ...]:
+  by_ref: dict[Ref, Node] = {}
+  for row in values:
+    current = by_ref.get(row.pin.ref)
+    if current is not None and current != row:
+      raise ValueError("context_slice_node_ref_ambiguous")
+    by_ref[row.pin.ref] = row
+  return tuple(sorted(by_ref.values(), key=lambda row: pin_key(row.pin)))
+
+
+def _nodes_by_ref(values: Sequence[Node]) -> dict[Ref, Node]:
+  return {row.pin.ref: row for row in values}
+
+
+def _ordered_nodes(
+  values: Sequence[Node],
+  order: Sequence[Pin],
+) -> tuple[Node, ...]:
+  by_pin = {row.pin: row for row in values}
+  if len(order) != len(set(order)) or set(order) != set(by_pin):
+    raise ValueError("context_slice_node_order_invalid")
+  return tuple(by_pin[pin] for pin in order)
+
+
+def _links(values: Sequence[Link]) -> tuple[Link, ...]:
+  by_id: dict[str, Link] = {}
+  for row in values:
+    current = by_id.get(row.id)
+    if current is not None and current != row:
+      raise ValueError("context_slice_link_id_conflict")
+    by_id[row.id] = row
+  return tuple(by_id[key] for key in sorted(by_id))
+
+
+def _ordered_links(
+  values: Sequence[Link],
+  order: Sequence[str],
+) -> tuple[Link, ...]:
+  by_id = {row.id: row for row in values}
+  if len(order) != len(set(order)) or set(order) != set(by_id):
+    raise ValueError("context_slice_link_order_invalid")
+  return tuple(by_id[item_id] for item_id in order)
+
+
+def _policies(values: Sequence[Policy]) -> tuple[Policy, ...]:
+  by_key: dict[tuple[str, str], Policy] = {}
+  for row in values:
+    key = policy_key(row)
+    current = by_key.get(key)
+    if current is not None and current != row:
+      raise ValueError("context_slice_policy_conflict")
+    by_key[key] = row
+  if not by_key:
+    raise ValueError("context_slice_policy_required")
+  return tuple(by_key[key] for key in sorted(by_key))
+
+
+def _omissions(values: Sequence[Omission]) -> tuple[Omission, ...]:
+  counts: dict[tuple[str, str, str], int] = {}
+  for row in values:
+    key = omission_key(row)
+    counts[key] = counts.get(key, 0) + row.count
+  return tuple(
+    Omission(owner=key[0], reason=key[1], selector=key[2], count=counts[key])
+    for key in sorted(counts)
+  )
+
+
+def _limit_omissions(values: Sequence[Omission], limit: int) -> tuple[Omission, ...]:
+  canonical = _omissions(values)
+  if len(canonical) <= limit:
+    return canonical
+  retained = list(canonical[:max(0, limit - 1)])
+  removed = canonical[len(retained):]
+  retained.append(Omission(
+    owner="context",
+    reason="omission_limit",
+    selector="*",
+    count=sum(row.count for row in removed),
+  ))
+  return _omissions(retained)
+
+
+def _generated_omissions(
+  *,
+  nodes: int,
+  links: int,
+  byte_count: int,
+) -> list[Omission]:
+  output: list[Omission] = []
+  for reason, count in (
+    ("node_limit", nodes),
+    ("link_limit", links),
+    ("byte_limit", byte_count),
+  ):
+    if count:
+      output.append(Omission(
+        owner="context",
+        reason=reason,
+        selector="*",
+        count=count,
+      ))
+  return output
+
+
+def _required(
+  roots: Sequence[Ref],
+  links: Sequence[Link],
+  nodes_by_ref: dict[Ref, Node],
+) -> set[Pin]:
+  refs = {
+    *roots,
+    *(ref for row in links for ref in (row.source, row.target)),
+  }
+  return {
+    *(row.owner for row in links),
+    *(nodes_by_ref[ref].pin for ref in refs if ref in nodes_by_ref),
+  }
+
+
+def _payload(
+  *,
+  purpose: str,
+  roots: tuple[Ref, ...],
+  effective_as_of: AwareDatetime,
+  observed_before: AwareDatetime,
+  nodes: Sequence[Node],
+  links: Sequence[Link],
+  omissions: tuple[Omission, ...],
+  policies: tuple[Policy, ...],
+  limits: Limits,
+) -> dict[str, Any]:
+  canonical_nodes = tuple(sorted(nodes, key=lambda node: pin_key(node.pin)))
+  canonical_links = tuple(sorted(links, key=lambda row: row.id))
+  truncated = tuple(sorted({
+    row.reason
+    for row in omissions
+    if row.owner == "context" and row.reason.endswith("_limit")
+  }))
+  payload: dict[str, Any] = {
+    "schema_version": 2,
+    "untrusted": True,
+    "purpose": purpose,
+    "roots": [row.model_dump(mode="json") for row in roots],
+    "effective_as_of": _time(effective_as_of),
+    "observed_before": _time(observed_before),
+    "nodes": [row.model_dump(mode="json") for row in canonical_nodes],
+    "links": [row.model_dump(mode="json") for row in canonical_links],
+    "bounds": Bounds(
+      limits=limits,
+      nodes=len(canonical_nodes),
+      links=len(canonical_links),
+      omissions=len(omissions),
+      truncated=truncated,
+      content_bytes=0,
+    ).model_dump(mode="json"),
+    "omissions": [row.model_dump(mode="json") for row in omissions],
+    "policies": [row.model_dump(mode="json") for row in policies],
+    "content_hash": "sha256:" + "0" * 64,
+  }
+  _settle_content_bytes(payload)
+  payload["content_hash"] = stable_hash([
+    "context-slice-v2",
+    {key: value for key, value in payload.items() if key != "content_hash"},
+  ])
+  return payload
+
+
+def _settle_content_bytes(payload: dict[str, Any]) -> None:
+  for _ in range(8):
+    size = len(canonical_json_bytes(payload))
+    if payload["bounds"]["content_bytes"] == size:
+      return
+    payload["bounds"]["content_bytes"] = size
+  raise ValueError("context_slice_content_bytes_unstable")
+
+
+def _time(value: AwareDatetime) -> str:
+  parsed = _AWARE_DATETIME.validate_python(value)
+  return cast(str, _AWARE_DATETIME.dump_python(parsed, mode="json"))

agos_context/graph.py

@@ -0,0 +1,280 @@
+"""Minimal immutable carrier for authorized context reads."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from typing import Annotated, Literal, cast
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field, model_validator
+
+
+Owner = Annotated[str, Field(pattern=r"^[a-z][a-z0-9_]{0,63}$")]
+RecordClass = Literal["record", "subject", "evidence", "receipt"]
+Family = Literal["structure", "source", "correction", "association"]
+type _JsonValue = None | bool | int | float | str | list[_JsonValue] | dict[str, _JsonValue]
+
+
+def _json_value(value: object) -> _JsonValue:
+  if value is None:
+    return value
+  if type(value) is bool:
+    return value
+  if type(value) is int:
+    return value
+  if type(value) is float:
+    if not math.isfinite(value):
+      raise ValueError("canonical JSON numbers must be finite")
+    return value
+  if type(value) is str:
+    return value
+  if type(value) is list:
+    return [_json_value(item) for item in cast(list[object], value)]
+  if type(value) is dict:
+    items = cast(dict[object, object], value)
+    for key in items:
+      if type(key) is not str:
+        raise TypeError(f"canonical JSON object keys must be strings, got {type(key).__name__}")
+    return {cast(str, key): _json_value(item) for key, item in items.items()}
+  raise TypeError(f"{type(value).__name__} is not a canonical JSON value")
+
+
+def canonical_json_bytes(value: object) -> bytes:
+  return json.dumps(
+    _json_value(value),
+    sort_keys=True,
+    separators=(",", ":"),
+    ensure_ascii=True,
+    allow_nan=False,
+  ).encode("utf-8")
+
+
+def stable_hash(value: object) -> str:
+  return f"sha256:{hashlib.sha256(canonical_json_bytes(value)).hexdigest()}"
+
+
+class GraphModel(BaseModel):
+  model_config = ConfigDict(
+    extra="forbid",
+    frozen=True,
+    revalidate_instances="always",
+    str_strip_whitespace=True,
+  )
+
+
+class Ref(GraphModel):
+  owner: Owner
+  kind: str = Field(pattern=r"^[a-z][a-z0-9_]{0,63}$")
+  id: str = Field(min_length=1, max_length=512)
+
+
+class Pin(GraphModel):
+  ref: Ref
+  revision: str = Field(min_length=1, max_length=256)
+
+
+class Node(GraphModel):
+  pin: Pin
+  record_class: RecordClass
+  label: str = Field(min_length=1, max_length=240)
+
+
+class Link(GraphModel):
+  id: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+  owner: Pin
+  source: Ref
+  predicate: str = Field(pattern=r"^[a-z][a-z0-9_]{0,63}\.[a-z][a-z0-9_]{0,63}$")
+  target: Ref
+  family: Family
+
+  @model_validator(mode="after")
+  def _identity(self) -> "Link":
+    if self.predicate.partition(".")[0] != self.owner.ref.owner:
+      raise ValueError("context_link_owner_mismatch")
+    if self.id != stable_hash([
+      "context-link-v1",
+      self.model_dump(mode="json", exclude={"id"}),
+    ]):
+      raise ValueError("context_link_id_mismatch")
+    return self
+
+
+def link(
+  *,
+  owner: Pin,
+  source: Ref,
+  predicate: str,
+  target: Ref,
+  family: Family,
+) -> Link:
+  """Construct one content-addressed context link."""
+
+  payload = {
+    "owner": owner.model_dump(mode="json"),
+    "source": source.model_dump(mode="json"),
+    "predicate": predicate,
+    "target": target.model_dump(mode="json"),
+    "family": family,
+  }
+  return Link.model_validate({
+    "id": stable_hash(["context-link-v1", payload]),
+    **payload,
+  })
+
+
+class Omission(GraphModel):
+  owner: Owner
+  reason: str = Field(pattern=r"^[a-z][a-z0-9_.]{0,127}$")
+  selector: str = Field(min_length=1, max_length=512)
+  count: int = Field(default=1, ge=1, strict=True)
+
+
+class Policy(GraphModel):
+  owner: Owner
+  name: str = Field(pattern=r"^[a-z][a-z0-9_]{0,63}$")
+  revision: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+
+
+class Contribution(GraphModel):
+  """One owner's closed, immutable contribution to a context slice."""
+
+  owner: Owner
+  nodes: tuple[Node, ...] = Field(default=(), max_length=500)
+  links: tuple[Link, ...] = Field(default=(), max_length=1_000)
+  omissions: tuple[Omission, ...] = Field(default=(), max_length=200)
+  policies: tuple[Policy, ...] = Field(min_length=1, max_length=20)
+
+  @model_validator(mode="after")
+  def _closed_owner_contribution(self) -> "Contribution":
+    pins = tuple(node.pin for node in self.nodes)
+    refs = tuple(pin.ref for pin in pins)
+    if len(set(pins)) != len(pins) or len(set(refs)) != len(refs):
+      raise ValueError("context_contribution_node_duplicated")
+    if len({row.id for row in self.links}) != len(self.links):
+      raise ValueError("context_contribution_link_duplicated")
+    available_pins = set(pins)
+    available_refs = set(refs)
+    for row in self.links:
+      if row.owner.ref.owner != self.owner:
+        raise ValueError("context_contribution_link_owner_mismatch")
+      if row.owner not in available_pins:
+        raise ValueError("context_contribution_link_owner_missing")
+      if row.source not in available_refs or row.target not in available_refs:
+        raise ValueError("context_contribution_link_ref_missing")
+    if any(row.owner != self.owner for row in self.omissions):
+      raise ValueError("context_contribution_omission_owner_mismatch")
+    if any(row.owner != self.owner for row in self.policies):
+      raise ValueError("context_contribution_policy_owner_mismatch")
+    return self
+
+
+class Limits(GraphModel):
+  max_nodes: int = Field(default=128, ge=1, le=500, strict=True)
+  max_links: int = Field(default=128, ge=0, le=1_000, strict=True)
+  max_omissions: int = Field(default=100, ge=1, le=200, strict=True)
+  max_bytes: int = Field(default=500_000, ge=1_000, le=500_000, strict=True)
+
+
+class Bounds(GraphModel):
+  limits: Limits
+  nodes: int = Field(ge=1, strict=True)
+  links: int = Field(ge=0, strict=True)
+  omissions: int = Field(ge=0, strict=True)
+  truncated: tuple[str, ...] = Field(default=(), max_length=4)
+  content_bytes: int = Field(ge=0, strict=True)
+
+
+class Slice(GraphModel):
+  schema_version: Literal[2] = 2
+  untrusted: Literal[True] = True
+  purpose: str = Field(pattern=r"^[a-z][a-z0-9_]{0,79}$")
+  roots: tuple[Ref, ...] = Field(min_length=1, max_length=20)
+  effective_as_of: AwareDatetime
+  observed_before: AwareDatetime
+  nodes: tuple[Node, ...] = Field(min_length=1, max_length=500)
+  links: tuple[Link, ...] = Field(default=(), max_length=1_000)
+  bounds: Bounds
+  omissions: tuple[Omission, ...] = Field(default=(), max_length=200)
+  policies: tuple[Policy, ...] = Field(min_length=1, max_length=20)
+  content_hash: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+
+  @model_validator(mode="after")
+  def _closed_canonical_slice(self) -> "Slice":
+    if self.roots != tuple(sorted(set(self.roots), key=ref_key)):
+      raise ValueError("context_slice_roots_not_canonical")
+    if self.nodes != tuple(sorted(self.nodes, key=lambda node: pin_key(node.pin))):
+      raise ValueError("context_slice_nodes_not_canonical")
+    if self.links != tuple(sorted(self.links, key=lambda row: row.id)):
+      raise ValueError("context_slice_links_not_canonical")
+    if len({row.id for row in self.links}) != len(self.links):
+      raise ValueError("context_slice_link_duplicated")
+    if self.omissions != tuple(sorted(self.omissions, key=omission_key)):
+      raise ValueError("context_slice_omissions_not_canonical")
+    if len({omission_key(row) for row in self.omissions}) != len(self.omissions):
+      raise ValueError("context_slice_omission_duplicated")
+    if self.policies != tuple(sorted(self.policies, key=policy_key)):
+      raise ValueError("context_slice_policies_not_canonical")
+    if len({policy_key(row) for row in self.policies}) != len(self.policies):
+      raise ValueError("context_slice_policy_duplicated")
+
+    pins = tuple(node.pin for node in self.nodes)
+    if len(set(pins)) != len(pins):
+      raise ValueError("context_slice_node_pin_duplicated")
+    refs = tuple(pin.ref for pin in pins)
+    if len(set(refs)) != len(refs):
+      raise ValueError("context_slice_node_ref_ambiguous")
+    available_refs = set(refs)
+    available_pins = set(pins)
+    if any(sum(pin.ref == root for pin in pins) != 1 for root in self.roots):
+      raise ValueError("context_slice_root_missing_or_ambiguous")
+    for row in self.links:
+      if row.owner not in available_pins:
+        raise ValueError("context_slice_link_owner_missing")
+      if row.source not in available_refs or row.target not in available_refs:
+        raise ValueError("context_slice_link_ref_missing")
+
+    if (
+      self.bounds.nodes != len(self.nodes)
+      or self.bounds.links != len(self.links)
+      or self.bounds.omissions != len(self.omissions)
+    ):
+      raise ValueError("context_slice_bounds_mismatch")
+    if (
+      len(self.nodes) > self.bounds.limits.max_nodes
+      or len(self.links) > self.bounds.limits.max_links
+      or len(self.omissions) > self.bounds.limits.max_omissions
+      or self.bounds.content_bytes > self.bounds.limits.max_bytes
+    ):
+      raise ValueError("context_slice_limit_exceeded")
+    expected_truncated = tuple(sorted({
+      row.reason
+      for row in self.omissions
+      if row.owner == "context" and row.reason.endswith("_limit")
+    }))
+    if self.bounds.truncated != expected_truncated:
+      raise ValueError("context_slice_truncation_mismatch")
+    if self.bounds.content_bytes != len(canonical_json_bytes(self.model_dump(mode="json"))):
+      raise ValueError("context_slice_content_bytes_mismatch")
+    if self.content_hash != stable_hash([
+      "context-slice-v2",
+      self.model_dump(mode="json", exclude={"content_hash"}),
+    ]):
+      raise ValueError("context_slice_content_hash_mismatch")
+    return self
+
+
+def ref_key(ref: Ref) -> tuple[str, str, str]:
+  return (ref.owner, ref.kind, ref.id)
+
+
+def pin_key(pin: Pin) -> tuple[str, str, str, str]:
+  return (*ref_key(pin.ref), pin.revision)
+
+
+def omission_key(row: Omission) -> tuple[str, str, str]:
+  return (row.owner, row.reason, row.selector)
+
+
+def policy_key(row: Policy) -> tuple[str, str]:
+  return (row.owner, row.name)