Observe the Decision Chain, Not Just the API Call

A successful API call can be the least important fact in an AI-assisted operating decision.

A model may answer. A policy service may return allow. A provider may accept a request. A queue may acknowledge a message. None of those observations, by itself, proves that a self-storage workflow used the right facility context, stayed within authority, produced the intended physical or financial effect, or reached a reconciled close.

Traditional application tracing is excellent at showing how software executed. Operators need an additional view: how a decision moved from evidence to recommendation, from recommendation to authority, from authority to action, and from action to verified operating state.

I call that view the decision chain.

This article proposes a trace model for AI-assisted self-storage work. It is designed for consequential workflows such as access exceptions, delinquency reviews, refunds, maintenance dispatch, rate changes, lead follow-up, and facility-status corrections. It is a reference method, not a product architecture, customer case study, or performance claim.

Open the full-size decision-chain diagram.

The operating question is larger than the software question

A distributed trace can answer questions such as:

• Which services handled the request?
• How long did each operation take?
• Where did an error occur?
• Which upstream call created the downstream work?

Those are necessary engineering questions. A self-storage operator also needs to ask:

• Which facility, unit, customer record, device, or work order did the decision concern?
• Which source governed each fact, and how fresh was it?
• What did the model recommend, using which model, prompt, retrieval snapshot, and rules?
• Was the recommendation informational, reviewable, or authorized to act?
• Who had the right to approve it for this facility and consequence class?
• What command was issued, what did the receiving system accept, and what actually changed?
• Which governing source was read back after the action?
• What evidence supports closure, limitation, escalation, or rollback?

An API trace and a decision trace can share the same underlying telemetry. They are not the same assertion. Technical success should remain separate from operating completion.

One chain, eight stages

The reference chain has eight stages. A low-consequence workflow may combine stages. A high-consequence workflow may split them further. The important point is to preserve the boundaries.

1. Assemble facility context

facility.context.assemble identifies the stable facility scope, actor scope, governing sources, current policy version, freshness rules, relevant events, sensitivity class, and unresolved conflicts. Display names are not enough. The trace should use a stable, opaque facility reference and retain the translation used when systems disagree about identifiers.

If identity, scope, or a required source is ambiguous, the decision chain should stop here. The model should not choose the nearest facility name or silently fill a missing state.

2. Create the recommendation

ai.recommendation.create records what the AI system was asked to do and the bounded recommendation it returned. Useful version fields include model, prompt, retrieval snapshot, tool configuration, rule set, and output schema. Evidence references should point to governed records or immutable snapshots; they should not copy unnecessary customer data into telemetry.

A fluent answer is still only a recommendation unless the declared workflow grants a narrower authority. The trace must not collapse “the model said” into “the business decided.”

3. Evaluate policy

policy.decision.evaluate records the applicable policy, version, effective time, authority scope, consequence class, decision, reason code, and enforcement point. A missing or conflicted policy should resolve to stop or review_required, never an implicit allow.

Policy evaluation and policy enforcement may happen in different components. Both need identifiers. A trace showing an allow decision without showing that the enforcement point honored it is incomplete.

4. Adjudicate human review

human.review.adjudicate records the reviewer role, facility scope, evidence packet, decision, limitations, and time. The trace should preserve whether the reviewer approved the recommendation, modified it, rejected it, or requested more evidence.

The reviewer’s name is not always needed in broadly accessible telemetry. A role reference and protected audit record may be safer. What must remain visible is that a qualified human actually held the decision right at that moment.

5. Issue the operating command

operation.command.issue describes the exact requested change, its idempotency key, target system, authorization reference, expiration, and rollback owner. This is where a recommendation becomes a request to change operating state.

Commands should be narrow. “Resolve access problem” is not a good command. “Create a review task,” “dispatch an inspection,” and “apply this approved temporary access rule until this time” are distinguishable actions with different evidence and consequence.

6. Record provider or system acceptance

provider.request.accept records whether the receiving boundary accepted, rejected, queued, or deduplicated the request. Preserve the provider receipt or source record reference when available.

Acceptance is not execution. A 200 response, queue acknowledgment, or created work-order ID may prove that another system received work. It does not prove the gate moved, the refund settled, the repair occurred, the rate took effect, or the facility record became correct.

7. Read back governing state

source.state.reconcile queries the source that governs the intended result after an appropriate interval. It records observed state, observation time, source freshness, expected state, and any mismatch. A webhook can trigger readback; it should not replace readback when the consequence warrants independent verification.

When the receiving system is not the governing source, the trace should name both. A task system may show closed while the access system still shows the previous rule. The mismatch is the operating fact.

8. Close, limit, escalate, or roll back

case.close_or_limit gives the workflow its final operating state. Valid outcomes should include more than success and failure: reconciled, limited, awaiting_evidence, escalated, rolled_back, and unresolved are often more truthful.

Closure should name the evidence reference, responsible owner, retention class, and any remaining limitation. If the workflow cannot reconstruct why it closed, it did not produce a durable operating record.

Use traces, links, events, and operating states deliberately

OpenTelemetry defines a span as a representation of a single operation within a trace. Spans can contain attributes, events, status, and links to other span contexts. That makes the model useful for a decision chain, but the business meaning must be defined explicitly.

Parent-child spans fit synchronous or causally nested work. Context assembly can be the parent of a policy evaluation executed within the same request.

Span links fit asynchronous work. A provider receipt arriving hours later, a maintenance record created in another system, or a reconciliation process running on a schedule can link back to the originating decision without pretending it occurred in one uninterrupted call stack.

Span events fit important observations within an operation: source_conflict_detected, human_review_required, provider_receipt_observed, reconciliation_mismatch, or rollback_started.

Technical status should report whether the operation executed as designed. Operating state should report whether the workflow reached a supportable business outcome. A reconciliation span can be technically OK while its operating state is mismatch_detected. That is not contradictory; it is precise.

W3C Trace Context standardizes the traceparent and tracestate headers used to propagate trace context across systems. It helps connect work. It does not establish who had authority, whether the data was true, or whether the operating result was complete.

A minimum decision-trace envelope

A useful root record should carry a small, stable set of operating fields:

• decision.trace_id: a random workflow identifier, not a customer or unit identifier;
• facility.ref: an opaque stable facility reference;
• workflow.type: a controlled vocabulary such as access_exception or maintenance_dispatch;
• consequence.class: the declared risk or consequence tier;
• authority.policy_ref and authority.policy_version;
• context.snapshot_ref and its observation time;
• decision.version_refs: model, prompt, retrieval, rules, and tools as applicable;
• review.state and qualified reviewer role when required;
• action.request_ref, provider.receipt_ref, and reconciliation.evidence_ref;
• operating.state, separate from technical status;
• sensitivity.class and retention.class; and
• rollback.owner and closure limitation.

Do not put names, email addresses, phone numbers, gate codes, payment details, reusable credentials, session tokens, raw prompts containing customer information, or token-bearing URLs into trace attributes or propagated baggage. OpenTelemetry’s security guidance places responsibility for sensitive-data handling on the implementer and recommends data minimization, filtering, redaction, and access controls. Hashing a predictable identifier does not necessarily anonymize it.

A fictional access exception

The following example is fictional. It describes no real facility, customer, vendor, deployment, or outcome.

At FAC-DEMO-021, a demonstration workflow receives a report that an authorized renter cannot enter during the declared access window. The AI assistant finds a fresh facility-hours record, a recent access-policy version, an access-controller heartbeat, and a delinquency indicator that conflicts with the billing source.

The context span records the conflict rather than choosing the more convenient value. The model recommends a billing-source readback and a limited human review. It does not recommend a permanent access change.

The policy span classifies an access-rule change as consequential and requires an onsite or regional reviewer. A qualified reviewer authorizes a time-limited exception only after the billing source confirms the account state. The command span includes the facility reference, approved time window, idempotency key, and expiration.

The access provider accepts the request and returns a receipt. That receipt changes the operating state to accepted_not_verified, not access_restored. A later source-state readback confirms the temporary rule is active. The case closes as limited_and_reconciled with an automatic expiration and named follow-up owner.

If the provider had accepted the command but readback showed the old rule, the same technically successful API trace would produce a different operating outcome: reconciliation_mismatch, followed by escalation or rollback.

Six queries that expose weak automation

Once the fields are consistent, the trace store can support diagnostic questions that ordinary uptime monitoring misses:

1. Which decisions reached a command without a current policy version?
2. Which provider-accepted requests have no governing-source readback within the workflow’s declared interval?
3. Which AI recommendations were modified or rejected by qualified reviewers, grouped by reason code and version set?
4. Which facility workflows repeatedly stop because identity translation, freshness, or authority scope is missing?
5. Which cases closed while the last reconciliation state was missing, stale, or mismatched?
6. Which rollback paths exist on paper but have no exercised evidence for the current policy or integration version?

These are control questions, not performance claims. Telemetry sampling, retention, missing instrumentation, clock skew, and inconsistent field adoption can distort counts. A sampled trace population is not a trustworthy denominator unless the sampling method and exclusions are declared.

Sampling and retention should follow consequence

Keeping every trace forever is neither necessary nor responsible. Keeping only the fastest or most successful traces is also misleading.

A consequence-aware policy can retain:

• all traces that change access, money, customer status, facility identity, or safety-relevant state;
• all human overrides, policy stops, reconciliation mismatches, and rollbacks;
• a declared sample of low-consequence informational workflows;
• the minimum evidence required for the applicable operating and legal retention period; and
• aggregated metrics only when numerator, denominator, sampling, exclusions, and observation period are reconstructable.

Tail sampling can be useful because it makes a keep-or-drop decision after more of the trace is visible. It can retain error or high-consequence paths that head sampling might discard. It still requires a declared policy, and it does not turn a sampled trace store into a complete operating ledger.

A release gate for decision-chain observability

Before an AI-assisted workflow is allowed to govern consequential self-storage work, verify:

• the workflow has a stable decision identifier that contains no customer data;
• facility identity and actor scope are explicit;
• governing sources, freshness rules, and conflicts are traceable;
• model, prompt, retrieval, rule, and tool versions are recorded when relevant;
• recommendation, policy decision, human adjudication, and enforcement are separate states;
• command, provider acceptance, execution evidence, and source reconciliation are separate states;
• technical status cannot overwrite operating state;
• asynchronous receipts and readbacks link to the originating decision;
• sensitive data is excluded or transformed before export;
• access to trace data follows least privilege;
• clock, retry, duplicate, timeout, and late-arrival behavior are tested;
• sampling and retention follow declared consequence and privacy rules;
• closure states include limitation, escalation, rollback, and unresolved outcomes; and
• an operator can reconstruct one fictional decision without reading application code.

Run the tabletop

Download the decision-chain observability template. It contains one eight-stage fictional access-exception exercise and no real customer, facility, vendor, or product data.

With an operator, source owner, security reviewer, and engineer:

1. Replace the fictional workflow with one bounded process.
2. Assign each stage to its authoritative evidence source.
3. Remove the policy version. Confirm the workflow stops.
4. Return a successful provider receipt but an unchanged governing source. Confirm the case remains open.
5. Delay the receipt until after the human review. Confirm the link preserves causality without rewriting time.
6. Insert a customer name, gate code, or token into a test attribute. Confirm the telemetry control removes or blocks it.
7. Ask a second reviewer to reconstruct the decision using only the retained trace and protected evidence references.

The exercise succeeds when the team can explain not only what the software did, but what the business was allowed to decide and what the operation can prove.

Sources and limitations

Observed August 22, 2026:

• OpenTelemetry Tracing API, defining spans, attributes, events, links, status, and trace context.
• OpenTelemetry: Handling sensitive data, modified January 14, 2026, describing implementer responsibility, data minimization, filtering, redaction, and access controls.
• W3C Trace Context, W3C Recommendation dated November 23, 2021.
• CloudEvents specification repository, listing v1.0.2 as the latest released core specification while the main line remains work in progress.
• W3C PROV-O, W3C Recommendation dated April 30, 2013, for representing entities, activities, agents, and provenance.
• NIST AI Risk Management Framework program page, describing AI RMF 1.0 as voluntary and noting that it is being revised.
• NIST Cybersecurity Framework 2.0, published February 26, 2024, including the Govern function.

These sources inform the transport, telemetry, provenance, cybersecurity, and AI-risk concepts used here. None defines this eight-stage self-storage decision chain, certifies an implementation, or proves an operating result. OpenTelemetry and W3C Trace Context describe observability and propagation mechanics; they do not establish business authority. CloudEvents describes interoperable event metadata; it does not guarantee delivery or operating completion. NIST frameworks are voluntary, cross-sectoral guidance.

Disclosure

I am CEO and Co-Founder of Facily.ai and Chief Operating Officer of modSTORAGE. This article presents a proposed operating and observability method. It is not a Facily OS release specification, a product-availability claim, a customer deployment, a measured modSTORAGE result, an industry standard, or independent validation.