mineproductivity 2.0.0__py3-none-any.whl

mineproductivity/README.md

@@ -0,0 +1,31 @@
+# mineproductivity (package root)
+
+## Purpose
+
+The single installable Python package containing every MineProductivity subsystem, organized as independently documented sub-packages with an enforced, inward-pointing dependency direction.
+
+## Scope
+
+The `src/` layout root for the `mineproductivity` distribution. Contains 24 subsystem packages plus the package-level `__init__.py` exposing `__version__`. Does not contain tests (see `tests/`), datasets (see `datasets/`), or documentation (see `docs/`).
+
+## Responsibilities
+
+- Expose the package version and top-level public API surface (currently empty).
+- House all subsystem sub-packages listed below, each independently documented.
+
+## Contents
+
+- `core/`, `events/`, `ontology/`, `kpis/`, `datasets/`, `connectors/`, `analytics/`, `optimization/`, `simulation/`, `digital_twin/`, `decision/`, `agents/`, `visualization/`, `benchmark/`, `certification/`, `config/`, `io/`, `utils/`, `typing/`, `cli/`, `exceptions/`, `registry/`, `plugins/`, `validation/`
+
+## Dependencies
+
+No third-party runtime dependencies are declared yet (see pyproject.toml). Internal dependency direction between sub-packages is documented in the root README.md.
+
+## Future Work
+
+Implement each sub-package per the phasing in ROADMAP.md, always starting with tests and metadata before behavior.
+
+## References
+
+- Master Architecture Handbook v1.0
+- Reference Implementation Blueprint v1.0

mineproductivity/__init__.py

@@ -0,0 +1,50 @@
+"""MineProductivity — a metadata-first, ontology-driven, event-sourced
+platform for mining productivity intelligence.
+
+The ``mineproductivity.core`` package contains the platform's foundational
+framework primitives (entities, value objects, identifiers, specifications,
+repositories, and friends). The ``mineproductivity.events`` package
+implements the immutable, append-only event model (Event Sourcing) built on
+it, per the locked Event Framework Design Specification. The
+``mineproductivity.ontology`` package implements the full typed,
+machine-readable domain vocabulary (ten sub-ontology families,
+relationships, contextual validation, and the Knowledge Graph projection
+contract) per the locked Ontology Framework Design Specification. The
+``mineproductivity.registry`` and ``mineproductivity.plugins`` packages
+implement the plugin-first discovery-and-lifecycle backbone (the generic
+``Registry`` mechanism, entry-point discovery, and version-gated,
+isolation-guaranteed plugin activation) per the locked Registry Framework
+Design Specification. The ``mineproductivity.connectors`` package
+implements the vendor-neutral ingestion boundary (the ``FMSConnector``
+contract, reference file/network/streaming connectors, and
+documentation-only OEM adapter shapes) per the locked Connector Framework
+Design Specification. The ``mineproductivity.kpis`` package now implements
+the metric backbone -- the metadata-first, self-describing KPI Engine (the
+``BaseKPI``/``CompositeKPI`` object model, dependency-graph orchestration,
+pluggable execution backends, and the 12-KPI Standard Library reference
+implementation) per the locked KPI Engine Design Specification. The
+``mineproductivity.analytics`` package implements the statistical and
+analytical computation layer built directly on ``kpis`` -- trend, baseline,
+and benchmark analysis, rolling and aggregate statistics, data-quality
+scoring, batch/streaming/incremental execution modes, and the plugin
+registry -- per the locked Analytics Engine Design Specification. The
+``mineproductivity.decision`` package implements the platform's
+prescriptive layer built directly on ``analytics`` -- rule/policy-driven
+decision strategies, ranking, explanation, prioritization, action
+planning, alerting, real-time and batch decision execution, and an
+append-only decision audit trail -- per the locked Decision Intelligence
+Design Specification. The ``mineproductivity.digital_twin``,
+``mineproductivity.simulation``, and ``mineproductivity.optimization``
+packages implement the stateful representation, projection, and
+prescriptive-search layers respectively, ``mineproductivity.agents``
+implements the model-independent agent-orchestration layer, and
+``mineproductivity.visualization`` implements the presentation layer --
+the final package in the architecture -- each per its own locked design
+specification. Every package in the locked dependency chain is now
+implemented. See the root README.md and docs/architecture/README.md for
+the governing architecture, and ROADMAP.md for the implementation
+phasing.
+"""
+
+__version__ = "2.0.0"
+__all__ = ["__version__"]

mineproductivity/agents/README.md

@@ -0,0 +1,27 @@
+# mineproductivity.agents
+
+## Purpose
+
+The AI-agent orchestration layer (design spec 11) — a model-independent orchestration layer for autonomous and semi-autonomous work, built directly above `optimization`. It defines *how* agent work is governed (`AgentPolicy`/`PolicyEngine`/`AgentCapabilitySet`), gated (`ApprovalRequest`), executed (`Task`/`TaskExecutor`), decomposed and delegated (`Goal`/`WorkflowEngine`/`AgentMessage`/`DelegationRequest`), and audited (`AgentAuditTrail`) — while `Agent`, `Tool`, and `AgentMemory` remain interface-only extension points: choosing a reasoning backend is exactly the implementation decision this package excludes.
+
+## Governing documents
+
+- [`docs/architecture/11_AI_Agents_Design_Specification.md`](../../../docs/architecture/11_AI_Agents_Design_Specification.md)
+- [`docs/design/11_AI_Agents_Implementation_Checklist.md`](../../../docs/design/11_AI_Agents_Implementation_Checklist.md)
+- [`docs/adr/ADR-0011-AI-Agents.md`](../../../docs/adr/ADR-0011-AI-Agents.md)
+
+## Scope
+
+**What belongs here:** agent/task/policy/approval/workflow/audit orchestration contracts and their reference execution path.
+
+**What must never belong here:** a concrete `Agent`, `Tool`, or `AgentMemory` implementation; any LLM-provider SDK coupling; any recomputation of a KPI, statistical, decision, twin-state, simulation, or optimization fact a lower package already owns.
+
+## Dependencies
+
+**Depends on:** `core`, `events` (transport for `AgentMessage`, composed by callers), `registry`, `connectors` (`RetryPolicy` as the retry-configuration shape, per spec 11 §12), `kpis`, `analytics`, `decision` (`Explanation` reused directly), `digital_twin`, `simulation`, `optimization`.
+
+**Depended on by:** `visualization` (future). No lower package imports `agents`.
+
+## Extension points
+
+Register a concrete `Agent` with `@register` (entry-point group `mineproductivity.agents`) and a concrete `Tool` with `@register_tool` (group `mineproductivity.agents.tools`); implement a `TaskRepository` backend as a `core.BaseRepository[Task, str]`; subclass `AgentMemory` for a memory backend (wired per-agent, not globally discovered).

mineproductivity/agents/__init__.py

@@ -0,0 +1,85 @@
+"""``mineproductivity.agents`` -- the AI-agent orchestration layer
+(design spec 11): a model-independent orchestration layer for
+autonomous and semi-autonomous work, built directly above
+``optimization``. Defines *how* agent work is governed, gated,
+executed, delegated, and audited -- ``Agent``/``Tool``/``AgentMemory``
+are interface-only extension points; choosing a reasoning backend is
+exactly the implementation decision this package excludes (§3.1, §4).
+
+Public API (design spec §7) -- every name stable once implementation
+begins.
+"""
+
+from __future__ import annotations
+
+from mineproductivity.agents._registry import REGISTRY, TOOLS, register, register_tool
+from mineproductivity.agents.abstractions import Agent, AgentContext
+from mineproductivity.agents.approval import ApprovalRequest, ApprovalStatus
+from mineproductivity.agents.audit import AgentAuditEntry, AgentAuditTrail
+from mineproductivity.agents.capability import AgentCapabilitySet, Permission
+from mineproductivity.agents.communication import AgentMessage, DelegationRequest
+from mineproductivity.agents.conversation import ConversationContext, ConversationTurn
+from mineproductivity.agents.discovery import by_category, by_scope
+from mineproductivity.agents.exceptions import (
+    AgentExecutionError,
+    AgentValidationError,
+    AgentVersionConflictError,
+    PermissionDeniedError,
+    PolicyConflictError,
+    TaskNotFoundError,
+)
+from mineproductivity.agents.executor import TaskExecutor
+from mineproductivity.agents.goal import Goal
+from mineproductivity.agents.memory import AgentMemory
+from mineproductivity.agents.metadata import AgentCategory, AgentMetadata
+from mineproductivity.agents.persistence import TaskRepository
+from mineproductivity.agents.policy import AgentPolicy, PolicyEngine, PolicyStatus
+from mineproductivity.agents.result import AgentResult
+from mineproductivity.agents.state import TaskState
+from mineproductivity.agents.task import Task, TaskStatus
+from mineproductivity.agents.tool import Tool, ToolInvocation, ToolMetadata
+from mineproductivity.agents.workflow import WorkflowEngine
+
+__all__ = [
+    "Agent",
+    "AgentAuditEntry",
+    "AgentAuditTrail",
+    "AgentCapabilitySet",
+    "AgentCategory",
+    "AgentContext",
+    "AgentExecutionError",
+    "AgentMemory",
+    "AgentMessage",
+    "AgentMetadata",
+    "AgentPolicy",
+    "AgentResult",
+    "AgentValidationError",
+    "AgentVersionConflictError",
+    "ApprovalRequest",
+    "ApprovalStatus",
+    "ConversationContext",
+    "ConversationTurn",
+    "DelegationRequest",
+    "Goal",
+    "Permission",
+    "PermissionDeniedError",
+    "PolicyConflictError",
+    "PolicyEngine",
+    "PolicyStatus",
+    "REGISTRY",
+    "TOOLS",
+    "Task",
+    "TaskExecutor",
+    "TaskNotFoundError",
+    "TaskRepository",
+    "TaskState",
+    "TaskStatus",
+    "Tool",
+    "ToolInvocation",
+    "ToolMetadata",
+    "WorkflowEngine",
+    "by_category",
+    "by_scope",
+    "register",
+    "register_tool",
+]

mineproductivity/agents/_registry.py

@@ -0,0 +1,84 @@
+"""The Agent Registry and the Tool Registry (design spec §22) -- two
+typed specializations of ``registry.Registry``, the first package in
+this series to hold two distinct ``Registry`` instances rather than
+one, since an ``Agent`` type and a ``Tool`` type are orthogonal
+registrable concepts (§22): an ``Agent`` decides; a ``Tool`` acts at
+an ``Agent``'s direction. The two are never merged. Both answer the
+type-level question ("which types are known"), never conflated with
+``TaskRepository`` (instance-level) or ``discovery.py`` (query
+facade). Entry-point discovery uses ``registry.EntryPointDiscovery``
+with ``EntryPointSpec(group="mineproductivity.agents",
+target_registry="agents")`` and
+``EntryPointSpec(group="mineproductivity.agents.tools",
+target_registry="agents.tools")`` (design spec §31), exactly as every
+prior domain package already wires its own group.
+"""
+
+from __future__ import annotations
+
+from mineproductivity.registry import Registry
+
+from mineproductivity.agents.abstractions import Agent
+from mineproductivity.agents.exceptions import (
+    AgentValidationError,
+    AgentVersionConflictError,
+)
+from mineproductivity.agents.tool import Tool
+
+__all__ = ["REGISTRY", "TOOLS", "register", "register_tool"]
+
+REGISTRY: Registry[str, type[Agent]] = Registry(name="agents")
+TOOLS: Registry[str, type[Tool]] = Registry(name="agents.tools")
+
+
+def register(cls: type[Agent]) -> type[Agent]:
+    """Register ``cls`` into :data:`REGISTRY`, keyed by
+    ``cls.meta.code``.
+
+    Raises
+    ------
+    AgentValidationError
+        If ``cls.meta.code`` is empty (defensive, redundant guard --
+        ``AgentMetadata.validate()`` already rejects it).
+    AgentVersionConflictError
+        If ``cls.meta.code`` is already registered -- add-only, raised
+        at registration time, never deferred (design spec §26).
+    """
+    if not cls.meta.code:
+        raise AgentValidationError(f"{cls.__name__}.meta.code must not be empty")
+
+    result = REGISTRY.register(cls.meta.code, cls, metadata=cls.meta)
+    if result.is_err:
+        raise AgentVersionConflictError(
+            f"Agent code {cls.meta.code!r} is already registered; changing what it "
+            f"means requires a new code or a reviewed version bump, not "
+            f"re-registration"
+        )
+
+    return cls
+
+
+def register_tool(cls: type[Tool]) -> type[Tool]:
+    """Register ``cls`` into :data:`TOOLS`, keyed by ``cls.meta.code``
+    -- identical shape and identical error semantics as
+    :func:`register`, specialized for ``Tool`` (design spec §22).
+
+    Raises
+    ------
+    AgentValidationError
+        If ``cls.meta.code`` is empty.
+    AgentVersionConflictError
+        If ``cls.meta.code`` is already registered in :data:`TOOLS`.
+    """
+    if not cls.meta.code:
+        raise AgentValidationError(f"{cls.__name__}.meta.code must not be empty")
+
+    result = TOOLS.register(cls.meta.code, cls, metadata=cls.meta)
+    if result.is_err:
+        raise AgentVersionConflictError(
+            f"Tool code {cls.meta.code!r} is already registered; changing what it "
+            f"means requires a new code or a reviewed version bump, not "
+            f"re-registration"
+        )
+
+    return cls

mineproductivity/agents/abstractions.py

@@ -0,0 +1,113 @@
+"""``Agent``: the "Agent-as-object" root, and ``AgentContext``, the
+collaborator/evidence bundle a concrete agent reasons over (design
+spec §8).
+
+Reuse audit: ``AgentContext`` mirrors
+``optimization.OptimizationContext`` (spec 10 §8) one layer up,
+extended with ``optimization_results`` -- an agent may read an
+already-solved plan a not-yet-solved ``OptimizationProblem`` could
+never reference. Evidence is read, never re-derived (§3.2), and
+assembly happens once, at construction -- never re-fetched per retry
+or per delegation (§27, §36). Per ``decision.DecisionContext``'s own
+established convention (spec 07 §8), the caller-assembles pattern is
+used exclusively. ``Agent`` shares one abstract method (``_act``)
+across all ten categories, mirroring ``decision.DecisionModel``'s
+shared-``_decide`` posture (spec 07 §8) rather than ``simulation``'s/
+``optimization``'s no-shared-method posture: every category answers
+the same underlying question -- given a task and context, decide what
+should happen next. THIS MODULE SHIPS NO CONCRETE SUBCLASS --
+choosing a specific reasoning backend (a hosted large-language-model
+service, a local model, a rule engine) is exactly the kind of
+implementation decision this package's charter (§3.1, §3.5, §4)
+excludes.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, ClassVar
+
+from mineproductivity.analytics import AnalyticsResult
+from mineproductivity.decision import DecisionResult
+from mineproductivity.digital_twin import TwinSnapshot
+from mineproductivity.kpis import KPIResult
+from mineproductivity.optimization import OptimizationResult
+from mineproductivity.simulation import SimulationResult
+
+from mineproductivity.agents.metadata import AgentMetadata
+
+if TYPE_CHECKING:
+    from mineproductivity.agents.result import AgentResult
+    from mineproductivity.agents.task import Task
+
+__all__ = ["Agent", "AgentContext"]
+
+
+class AgentContext:
+    """Bundles the evidence an ``Agent`` may need (design spec §8) --
+    carried once, at construction; every fact an agent reasons over
+    has a stable, structured home in a lower package, never a
+    re-derivation of its own.
+
+    Examples
+    --------
+    >>> context = AgentContext()
+    >>> context.kpi_results
+    ()
+    >>> context.twin_snapshot is None
+    True
+    """
+
+    def __init__(
+        self,
+        *,
+        kpi_results: Sequence[KPIResult] = (),
+        analytics_results: Sequence[AnalyticsResult] = (),
+        decision_results: Sequence[DecisionResult] = (),
+        twin_snapshot: TwinSnapshot | None = None,
+        simulation_results: Sequence[SimulationResult] = (),
+        optimization_results: Sequence[OptimizationResult] = (),
+    ) -> None:
+        self.kpi_results = tuple(kpi_results)
+        self.analytics_results = tuple(analytics_results)
+        self.decision_results = tuple(decision_results)
+        self.twin_snapshot = twin_snapshot
+        self.simulation_results = tuple(simulation_results)
+        self.optimization_results = tuple(optimization_results)
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(kpi_results={self.kpi_results!r}, "
+            f"analytics_results={self.analytics_results!r}, "
+            f"decision_results={self.decision_results!r}, "
+            f"twin_snapshot={self.twin_snapshot!r}, "
+            f"simulation_results={self.simulation_results!r}, "
+            f"optimization_results={self.optimization_results!r})"
+        )
+
+
+class Agent(ABC):
+    """The root of every registrable agent type (design spec §8) --
+    the direct counterpart of ``optimization.OptimizationModel`` one
+    layer down, whose category members (§29) are domain roles rather
+    than algorithmic paradigms.
+
+    **Statelessness.** Every subclass, of every category, is stateless
+    -- no instance attribute is mutated by any ``_act`` implementation
+    (§29, §32); statefulness lives entirely in ``Task`` (§11), so the
+    same registered ``Agent`` type can execute many concurrent
+    ``Task``\\ s safely.
+
+    **Qualify, don't coerce** (§30): no ``_act`` implementation raises
+    for a legitimately incomplete or ambiguous task -- it returns an
+    ``AgentResult`` carrying a warning instead.
+    """
+
+    meta: ClassVar[AgentMetadata]
+
+    @abstractmethod
+    def _act(self, task: Task, *, context: AgentContext) -> AgentResult:
+        """Given ``task`` and ``context``, decide what should happen
+        next -- the one shared reasoning call every category answers
+        (design spec §8)."""

mineproductivity/agents/approval.py

@@ -0,0 +1,56 @@
+"""``ApprovalRequest``/``ApprovalStatus``: the human-in-the-loop gate
+(design spec §16).
+
+Reuse audit: ``core.BaseValueObject`` reused verbatim. Genuinely new
+to this series: no package below ``agents`` pauses mid-execution for a
+human decision. An ``ApprovalRequest`` resolving to ``APPROVED``
+transitions its ``Task`` from ``AWAITING_APPROVAL`` back to
+``RUNNING``; a resolution to ``REJECTED`` transitions it directly to
+``FAILED``, carrying the rejection as a warning on the eventual
+``AgentResult`` (§16, §11). ``TaskExecutor`` never resolves an
+``ApprovalRequest`` itself -- resolution is exclusively a caller
+(human-supervisor-facing) action.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from datetime import datetime
+from enum import Enum
+
+from mineproductivity.core import BaseValueObject
+
+__all__ = ["ApprovalRequest", "ApprovalStatus"]
+
+
+class ApprovalStatus(Enum):
+    """The three-state approval lifecycle a ``Task`` pauses on when
+    ``PolicyEngine`` (design spec §10) requires it -- closed; a new
+    approval *policy* (who must approve what) is an ``AgentPolicy``
+    concern, not a change here."""
+
+    PENDING = "pending"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class ApprovalRequest(BaseValueObject):
+    """One pending, approved, or rejected request for a human to
+    authorize a ``Task`` before ``TaskExecutor`` (design spec §12)
+    resumes it.
+
+    Examples
+    --------
+    >>> request = ApprovalRequest(task_id="TASK-1", requested_action="approve_shutdown")
+    >>> request.status
+    <ApprovalStatus.PENDING: 'pending'>
+    >>> request.approver is None
+    True
+    """
+
+    task_id: str
+    requested_action: str
+    status: ApprovalStatus = dataclasses.field(default=ApprovalStatus.PENDING, kw_only=True)
+    approver: str | None = dataclasses.field(default=None, kw_only=True)
+    resolved_at: datetime | None = dataclasses.field(default=None, kw_only=True)

mineproductivity/agents/audit.py

@@ -0,0 +1,102 @@
+"""``AgentAuditTrail``/``AgentAuditEntry``: accountability for
+autonomous action (design spec §21), mirroring
+``decision.DecisionAuditTrail``'s pattern and rationale (spec 07 §27)
+-- the accountability mechanism an autonomous-action system requires
+even more urgently than a purely recommending one does.
+
+Thread safety (design spec §32): :meth:`AgentAuditTrail.record`
+serializes concurrent appends internally via one ``threading.Lock``,
+so many concurrently-executing ``Task``\\ s can share one trail
+instance safely; :meth:`AgentAuditTrail.query` reads a snapshot taken
+under the same lock, then filters outside it, so it never blocks on a
+concurrent ``record()`` beyond the snapshot itself. Every
+``AgentResult``'s ``explanation`` and every ``ToolInvocation`` it
+carries are preserved verbatim in the recorded entry -- an agent's
+audit record is never a summary, always the full, structured outcome.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import threading
+from collections.abc import Mapping, Sequence
+from datetime import datetime
+from types import MappingProxyType
+
+from mineproductivity.core import BaseValueObject
+
+from mineproductivity.agents.result import AgentResult
+
+__all__ = ["AgentAuditEntry", "AgentAuditTrail"]
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class AgentAuditEntry(BaseValueObject):
+    """One append-only record: which agent produced which result, for
+    what scope, when (design spec §21).
+
+    Examples
+    --------
+    >>> from datetime import timezone
+    >>> entry = AgentAuditEntry(
+    ...     recorded_at=datetime(2026, 7, 1, tzinfo=timezone.utc),
+    ...     result=AgentResult(task_id="TASK-1"),
+    ...     agent_code="FLEET.ReassignmentAdvisor", scope={"pit": "north"},
+    ... )
+    >>> dict(entry.scope)
+    {'pit': 'north'}
+    """
+
+    recorded_at: datetime
+    result: AgentResult
+    agent_code: str
+    scope: Mapping[str, str]
+
+    def _normalize(self) -> None:
+        super(AgentAuditEntry, self)._normalize()
+        object.__setattr__(self, "scope", MappingProxyType(dict(self.scope)))
+
+
+class AgentAuditTrail:
+    """Append-only record of every terminal ``AgentResult`` produced
+    by any ``TaskExecutor`` run in this process (design spec §21).
+    Serializes via ``core.serialization`` exactly as every other value
+    object in this platform does.
+
+    Examples
+    --------
+    >>> from datetime import timezone
+    >>> trail = AgentAuditTrail()
+    >>> trail.record(AgentAuditEntry(
+    ...     recorded_at=datetime(2026, 7, 1, tzinfo=timezone.utc),
+    ...     result=AgentResult(task_id="TASK-1"),
+    ...     agent_code="FLEET.ReassignmentAdvisor", scope={"pit": "north"},
+    ... ))
+    >>> len(trail.query())
+    1
+    >>> len(trail.query(scope={"pit": "south"}))
+    0
+    """
+
+    def __init__(self) -> None:
+        self._entries: list[AgentAuditEntry] = []
+        self._lock = threading.Lock()
+
+    def record(self, entry: AgentAuditEntry) -> None:
+        with self._lock:
+            self._entries.append(entry)
+
+    def query(self, *, scope: Mapping[str, str] | None = None) -> Sequence[AgentAuditEntry]:
+        with self._lock:
+            snapshot = tuple(self._entries)
+        if scope is None:
+            return snapshot
+        return tuple(
+            entry
+            for entry in snapshot
+            if all(entry.scope.get(key) == value for key, value in scope.items())
+        )
+
+    def __repr__(self) -> str:
+        with self._lock:
+            return f"{type(self).__name__}(entries={len(self._entries)})"

mineproductivity/agents/capability.py

@@ -0,0 +1,91 @@
+"""``Permission``/``AgentCapabilitySet``: authorization for autonomous
+action (design spec §9).
+
+Reuse audit: ``core.BaseValueObject`` and the
+``MappingProxyType``-freezing convention reused verbatim; ``scope``
+carries the same ontology-expressed vocabulary (equipment, pit, shift)
+``digital_twin.Twin.scope`` already carries (spec 08 §9), held as
+plain strings per Documentation Governance Rule #005. Genuinely new to
+this series: no package below ``agents`` models authorization, since
+none of them acts autonomously in the first place.
+
+Governance: an ``AgentCapabilitySet`` is always an explicit, authored,
+and governed artifact -- never inferred from an ``Agent`` subclass's
+own code at runtime (design spec §9). :func:`publish_capabilities`/
+:func:`published_capabilities` mirror ``optimization.publish_problem``'s
+process-wide governed store, keyed by ``agent_code``; neither is
+re-exported from the package's top-level ``__all__`` (design spec §7
+names ``Permission``/``AgentCapabilitySet`` only).
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import threading
+from collections.abc import Mapping
+from types import MappingProxyType
+
+from mineproductivity.core import BaseValueObject
+
+__all__ = ["AgentCapabilitySet", "Permission"]
+
+_capabilities: dict[str, AgentCapabilitySet] = {}
+_lock = threading.Lock()
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Permission(BaseValueObject):
+    """One capability a registered ``Agent`` is authorized to
+    exercise, scoped the same way ``digital_twin.Twin.scope`` already
+    is (design spec §9).
+
+    Examples
+    --------
+    >>> Permission(capability="approve_shutdown", scope={"pit": "north"}).capability
+    'approve_shutdown'
+    """
+
+    capability: str
+    scope: Mapping[str, str] = dataclasses.field(default_factory=dict, kw_only=True)
+
+    def _normalize(self) -> None:
+        super(Permission, self)._normalize()
+        object.__setattr__(self, "scope", MappingProxyType(dict(self.scope)))
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class AgentCapabilitySet(BaseValueObject):
+    """The full set of ``Permission``\\ s a registered ``Agent`` type
+    carries -- authored and governed, never inferred from an agent's
+    own code (design spec §9).
+
+    Examples
+    --------
+    >>> caps = AgentCapabilitySet(
+    ...     agent_code="FLEET.ReassignmentAdvisor",
+    ...     permissions=(Permission(capability="reassign_truck"),),
+    ... )
+    >>> caps.permissions[0].capability
+    'reassign_truck'
+    """
+
+    agent_code: str
+    permissions: tuple[Permission, ...]
+
+
+def publish_capabilities(capabilities: AgentCapabilitySet) -> AgentCapabilitySet:
+    """Publish ``capabilities`` into the process-wide governed store,
+    keyed by ``capabilities.agent_code`` (design spec §9, §31) -- the
+    explicit authoring step that makes a capability grant a
+    reviewable artifact."""
+    with _lock:
+        _capabilities[capabilities.agent_code] = capabilities
+        return capabilities
+
+
+def published_capabilities(agent_code: str) -> AgentCapabilitySet | None:
+    """Non-raising lookup of the currently-published capability set
+    for ``agent_code``, or ``None`` -- an agent with no published set
+    holds no permissions at all."""
+    with _lock:
+        return _capabilities.get(agent_code)