Audits and freshness

An inventory fact can be correct when recorded and wrong months later. Quilombo tracks whether a location or holding was confirmed, when it was observed, and which user authorized the audit. The audit event keeps the client-supplied provenance without storing source photos or videos.

Freshness states

Reads expose verification_status, last_observed_at, last_observed_by, and freshness for locations and holdings. freshness has three useful values:

• current: confirmed within the configured window;

• stale: confirmed, but older than the configured window;

• unknown: never confirmed, explicitly marked unknown, or changed since confirmation.

The default window is 90 days. Deployments can change it with INVENTORY_FRESHNESS_DAYS. Changing an item’s quantity, location, approximation flag, or notes invalidates the holding’s previous verification. Changing a location’s identity, description, metadata, or parent does the same for the location. Delayed audits are rejected when their observed_at is older than the stored observation.

Re-verify while already there

Freshness is a prompt for selective maintenance, not a reason to question every search result. An agent should suggest a related check only when all of these are true:

• the user is already opening or handling the exact location;

• another fact in that location is stale or unknown;

• checking it is quick and does not distract from the original task.

For example, suppose the user asks for screws stored in drawer unit > drawer 1. The same drawer contains a white box whose nuts have not been verified for months. After answering where the screws are, the agent can ask one short follow-up: “While drawer 1 is open, are the nuts still in the white box?” If those nuts were inventoried recently, the agent should not ask. It should not expand the check to other drawers or repeatedly ask about the same current facts.

A negative or uncertain answer is not proof that an item is absent. Mark the holding unknown unless the user confirms a correction or deletion.

Search results include the freshness and stable holding ID of nearby items in the same location. This lets a client make the selective suggestion without scanning unrelated locations. A scoped get_inventory_snapshot remains available when a deliberate location-wide audit is requested.

MCP audit

audit_inventory audits one known location and only the holdings explicitly listed. Omitted holdings remain unchanged. Each holding needs its stable holding_id and a status of confirmed or unknown; the same request may correct its quantity, approximation flag, or notes.

{
  "location_key": "drawer-1",
  "location_status": "confirmed",
  "holdings": [
    {
      "holding_id": "2f0f08af-2d15-4ea1-8ef6-02e505b41db4",
      "status": "confirmed",
      "quantity": "24"
    }
  ],
  "idempotency_key": "audit-drawer-1-20260823",
  "provenance": {
    "client_actor": "inventory-agent/1.0",
    "source_kind": "manual",
    "source_reference": "Drawer 1 checked with the user",
    "observed_at": "2026-08-23T10:30:00-03:00"
  }
}

The operation is transactional and idempotent. It creates an immutable audit event. Reusing the same idempotency key with a different payload is rejected.