EmbeddedSemantics

Use-case recipes

Put governed meaning at one useful boundary.

Choose a recipe by the durable handoff you need—not by the model you run.

Choose the workflow that matches your real handoff, copy the minimum request and client-record pattern, and keep every resolved, unknown, ambiguous, error, and authorization branch explicit.

Build a complete integration kit Study the recipes
01

Choose a durable boundary

Memory, routing, a record or event, clarification, or audit evidence—not every conversational turn.

02

Preserve every outcome

Keep the original expression, semantic outcome, and complete resolver evidence whether or not a code was assigned.

03

Authorize separately

Run a distinct policy check before any side effect. A resolved ConceptCode never grants permission.

Choose by workflow

Start with the boundary that already matters.

Review value and fit first →

One record contract across every recipe

The record shape stays predictable across all five recipes.

Resolve once at a durable memory, routing, record, clarification, or audit boundary—not on every conversational turn.

Accept identity: Accept identity only when data.status == "resolved" and data.concept.code is a non-empty string.
Abstention: Every abstained result means no ConceptCode assignment.
Authorization: A ConceptCode is semantic metadata only. Evaluate permission and side effects in a separate policy layer.

Always retain

  • originalExpression
  • language
  • semanticOutcome
  • resolverEvidence

Resolved branch only

  • conceptCode
  • registryVersion

Separate policy evidence

  • authorizationOutcome
  • authorizationPolicyVersion
  • downstreamActionOutcome
01

For desktop_agent · local_llm · knowledge_application

Multilingual agent memory

Store the original wording beside a resolved ConceptCode and registryVersion so later systems can refer to the same reviewed meaning without erasing the user's language.

Fit question

Will this reviewed meaning be written to durable memory and reused across sessions, languages, or models?

Good fit when
  • At the durable-memory write boundary, not on every conversational turn.
  • The same remembered idea may be expressed differently across sessions and languages.

Do not use this recipe when

  • The text is a transient conversational turn with no durable memory consumer.
  • The application cannot retain unresolved or ambiguous memory without inventing a code.

Best placement: At the durable-memory write boundary, not on every conversational turn.

Minimum request

No whole conversation or credentials
{
  "expression": "stable concept identity",
  "language": "en"
}

Client record

Type: semantic_memory

Always
  • originalExpressioncopy the exact submitted expression
  • languagecopy the submitted language tag or null when omitted
  • semanticOutcomeresolved, unknown_expression, ambiguous_expression, or request_or_service_error
  • resolverEvidenceretain the complete observed envelope or an immutable reference to it
Resolved only
  • conceptCodecopy data.concept.code exactly
  • registryVersioncopy data.concept.registryVersion exactly
Never store as authority:
  • candidate-derived, model-derived, translated, approximated, empty, or locally constructed ConceptCode
  • authorization inferred from semantic identity

Handle all four branches: resolved, unknown expression, ambiguous expression, and request or service error

resolved

data.status == "resolved" AND data.concept.code is a non-empty string

Concept assignment: copy exact returned code and registryVersion

  1. Store the original expression, semanticOutcome=resolved, exact ConceptCode, registryVersion, and resolver evidence.
  2. Use the code as semantic metadata for retrieval or deduplication while keeping the user's wording visible.

unknown expression

data.status == "abstained" AND data.reason == "unknown_expression"

Concept assignment: none

  1. Store the original expression with semanticOutcome=unknown_expression and no ConceptCode fields.
  2. Keep the memory searchable by its original text or local application metadata without claiming governed identity.

ambiguous expression

data.status == "abstained" AND data.reason == "ambiguous_expression"

Concept assignment: none

  1. Store semanticOutcome=ambiguous_expression and no ConceptCode fields.
  2. Ask for the missing context before creating a governed semantic link, or preserve the memory as unresolved.

request or service error

HTTP/input/service failure, malformed envelope, unsupported status, or resolved response without a non-empty code

Concept assignment: none

  1. Store or report semanticOutcome=request_or_service_error and no ConceptCode fields.
  2. Retry only according to the application's normal transport policy; never infer identity from a failed request.

Separate authorization gate

May this memory be stored, shared, synchronized, or disclosed under the application's separate privacy and access policy?

Run this check after semantic interpretation and before any side effect.

If denied: Preserve the semantic evidence but do not perform the action.

The ConceptCode organizes meaning; it does not authorize memory sharing or downstream actions.

Evidence to retain

  • original expression and language tag supplied by the client
  • complete resolver envelope
  • semantic outcome and abstention reason when present
  • exact ConceptCode and registryVersion only when resolved
  • separate memory-sharing authorization outcome

How to prove the benefit

Duplicate memory category rate

duplicate semantic categories / reviewed durable memory categories

Target: decrease without increasing wrong accepted identity
Unresolved memory visibility

unresolved memories retained with explicit outcome / all unresolved memories

Target: increase toward complete visibility
02

For desktop_agent · automation_builder · tool_runtime

Agent and workflow routing

A governed ConceptCode can become a stable semantic input to a separately authorized routing policy.

Fit question

Does an already-authorized routing policy need a stable governed semantic key at one decision boundary?

Good fit when
  • Immediately before a semantic routing decision whose policy already recognizes published codes.
  • Routing rules based only on free-text labels can drift or disagree between tools.

Do not use this recipe when

  • The caller expects semantic identity itself to authorize a tool or side effect.
  • The routing policy has no explicit handling for unknown, ambiguity, or service error.

Best placement: Immediately before a semantic routing decision whose policy already recognizes published codes.

Minimum request

No whole conversation or credentials
{
  "expression": "machine-readable representation",
  "language": "en"
}

Client record

Type: semantic_route_input

Always
  • originalExpressioncopy the exact submitted expression
  • languagecopy the submitted language tag or null when omitted
  • semanticOutcomeresolved, unknown_expression, ambiguous_expression, or request_or_service_error
  • resolverEvidenceretain the complete observed envelope or an immutable reference to it
Resolved only
  • conceptCodecopy data.concept.code exactly
  • registryVersioncopy data.concept.registryVersion exactly
Never store as authority:
  • candidate-derived, model-derived, translated, approximated, empty, or locally constructed ConceptCode
  • authorization inferred from semantic identity

Handle all four branches: resolved, unknown expression, ambiguous expression, and request or service error

resolved

data.status == "resolved" AND data.concept.code is a non-empty string

Concept assignment: copy exact returned code and registryVersion

  1. Copy the exact ConceptCode into the routing input only after the resolved acceptance predicate passes.
  2. Evaluate the independent allow/deny policy before selecting or executing any route.

unknown expression

data.status == "abstained" AND data.reason == "unknown_expression"

Concept assignment: none

  1. Assign no semantic route key and choose a documented non-semantic fallback or human review path.
  2. Do not use a local model's likely label as a replacement ConceptCode.

ambiguous expression

data.status == "abstained" AND data.reason == "ambiguous_expression"

Concept assignment: none

  1. Assign no semantic route key and request the smallest distinguishing clarification.
  2. Do not choose among candidates or possible meanings automatically.

request or service error

HTTP/input/service failure, malformed envelope, unsupported status, or resolved response without a non-empty code

Concept assignment: none

  1. Assign no semantic route key and keep the side effect blocked or use a documented safe default.
  2. Log the transport/input failure separately from semantic outcomes.

Separate authorization gate

Is this route and its side effect permitted for this user, application, resource, and current context?

Run this check after semantic interpretation and before any side effect.

If denied: Preserve the semantic evidence but do not perform the action.

A resolved identity may inform routing but never grants permission to execute a tool.

Evidence to retain

  • original expression
  • complete resolver envelope
  • resolved code/version or explicit no-assignment outcome
  • routing policy version
  • separate authorization decision and reason
  • selected route only after both semantic and authorization gates pass

How to prove the benefit

Wrong-route prevention

unsupported or ambiguous inputs blocked from semantic routing / all unsupported or ambiguous routing inputs

Target: increase toward complete prevention
Routing policy code consistency

authorized routes using exact published codes / all semantic routes

Target: increase toward complete consistency
03

For application_developer · api_designer · data_engineer

API, event, and record interoperability

Attach an exact ConceptCode and registryVersion to a record or event so recipients can inspect the same definition while retaining their own display language.

Fit question

Will an API, event, or stored record cross a boundary where another system benefits from inspecting the same governed definition?

Good fit when
  • At an API, event, or persistence boundary where semantic metadata is part of the contract.
  • Independent systems often use incompatible names for the same idea.

Do not use this recipe when

  • The receiving system does not need semantic metadata or cannot preserve the original expression.
  • The sender would omit the record entirely when the resolver abstains instead of representing no assignment.

Best placement: At an API, event, or persistence boundary where semantic metadata is part of the contract.

Minimum request

No whole conversation or credentials
{
  "expression": "semantic interoperability",
  "language": "en"
}

Client record

Type: semantic_event_metadata

Always
  • originalExpressioncopy the exact submitted expression
  • languagecopy the submitted language tag or null when omitted
  • semanticOutcomeresolved, unknown_expression, ambiguous_expression, or request_or_service_error
  • resolverEvidenceretain the complete observed envelope or an immutable reference to it
Resolved only
  • conceptCodecopy data.concept.code exactly
  • registryVersioncopy data.concept.registryVersion exactly
Never store as authority:
  • candidate-derived, model-derived, translated, approximated, empty, or locally constructed ConceptCode
  • authorization inferred from semantic identity

Handle all four branches: resolved, unknown expression, ambiguous expression, and request or service error

resolved

data.status == "resolved" AND data.concept.code is a non-empty string

Concept assignment: copy exact returned code and registryVersion

  1. Attach semanticOutcome=resolved, exact ConceptCode, registryVersion, and resolver evidence as metadata.
  2. Keep domain payload, display text, and authorization fields independent from semantic metadata.

unknown expression

data.status == "abstained" AND data.reason == "unknown_expression"

Concept assignment: none

  1. Emit semanticOutcome=unknown_expression with no ConceptCode or registryVersion fields.
  2. Preserve the original expression so receivers can display or review the unresolved meaning.

ambiguous expression

data.status == "abstained" AND data.reason == "ambiguous_expression"

Concept assignment: none

  1. Emit semanticOutcome=ambiguous_expression with no ConceptCode or registryVersion fields.
  2. Require clarification before a receiver treats the record as governed semantic identity.

request or service error

HTTP/input/service failure, malformed envelope, unsupported status, or resolved response without a non-empty code

Concept assignment: none

  1. Emit or log semanticOutcome=request_or_service_error according to the record contract, with no ConceptCode fields.
  2. Do not silently drop the failure or manufacture semantic metadata.

Separate authorization gate

May this event or record be emitted to the intended recipient under the separate data-sharing and access policy?

Run this check after semantic interpretation and before any side effect.

If denied: Preserve the semantic evidence but do not perform the action.

Do not replace domain data or access-control fields with a ConceptCode.

Evidence to retain

  • original expression and optional language
  • semantic outcome
  • exact ConceptCode and registryVersion only when resolved
  • complete resolver envelope or immutable evidence reference
  • event/record schema version
  • separate data-sharing authorization outcome

How to prove the benefit

Cross-system code consistency

records using the same exact code for the same reviewed meaning / compared resolved records

Target: increase
One-off mapping table reduction

retired local label mappings / baseline local label mappings

Target: increase while preserving unresolved records
04

For support_agent · desktop_agent · human_operator

Human clarification and safer assistance

The resolver's unknown and ambiguous outcomes give the interface a principled reason to preserve uncertainty, ask a targeted question, or continue without semantic identity.

Fit question

Would choosing the wrong meaning materially change the assistance, record, route, or next question?

Good fit when
  • At a decision point where choosing the wrong meaning would materially change the next step.
  • An agent may sound confident even when a phrase is unsupported or context-dependent.

Do not use this recipe when

  • No stable semantic identity is needed for the interaction.
  • The interface will present a guessed code as authoritative after unknown or ambiguity.

Best placement: At a decision point where choosing the wrong meaning would materially change the next step.

Minimum request

No whole conversation or credentials
{
  "expression": "semantic alignment",
  "language": "en"
}

Client record

Type: clarification_state

Always
  • originalExpressioncopy the exact submitted expression
  • languagecopy the submitted language tag or null when omitted
  • semanticOutcomeresolved, unknown_expression, ambiguous_expression, or request_or_service_error
  • resolverEvidenceretain the complete observed envelope or an immutable reference to it
Resolved only
  • conceptCodecopy data.concept.code exactly
  • registryVersioncopy data.concept.registryVersion exactly
Never store as authority:
  • candidate-derived, model-derived, translated, approximated, empty, or locally constructed ConceptCode
  • authorization inferred from semantic identity

Handle all four branches: resolved, unknown expression, ambiguous expression, and request or service error

resolved

data.status == "resolved" AND data.concept.code is a non-empty string

Concept assignment: copy exact returned code and registryVersion

  1. Explain that a governed identity was found and display the exact code or public definition when useful.
  2. Continue only after any independent action authorization is evaluated.

unknown expression

data.status == "abstained" AND data.reason == "unknown_expression"

Concept assignment: none

  1. Explain that no reviewed registry identity was found and assign no ConceptCode.
  2. Ask for more context only when it would help the user's task; otherwise continue without semantic identity.

ambiguous expression

data.status == "abstained" AND data.reason == "ambiguous_expression"

Concept assignment: none

  1. Explain that more than one governed interpretation remains possible and assign no ConceptCode.
  2. Ask one targeted question for the missing distinguishing context.

request or service error

HTTP/input/service failure, malformed envelope, unsupported status, or resolved response without a non-empty code

Concept assignment: none

  1. Explain that the request needs correction or the service could not return a trustworthy semantic result.
  2. Do not present transport success/failure as semantic identity.

Separate authorization gate

After the meaning is understood, is the proposed next action allowed and approved under the application's separate policy?

Run this check after semantic interpretation and before any side effect.

If denied: Preserve the semantic evidence but do not perform the action.

Do not frame abstention as a defect the local model should override.

Evidence to retain

  • original expression
  • semantic outcome and reason
  • clarifying question asked, if any
  • user-provided distinguishing context
  • exact code/version only after a later resolved request
  • separate authorization outcome for any action

How to prove the benefit

Clarification resolution quality

clarifications producing a reviewed resolved result or explicit preserved uncertainty / all clarification attempts

Target: increase without forcing resolution
Silent semantic assumption rate

material decisions made without resolved identity or explicit no-code handling / material semantic decisions

Target: decrease toward zero
05

For auditor · system_operator · governance_team

Audit, provenance, and explainability

A resolved record points to a published definition, reviewed expressions, provenance, and registry version that can be inspected independently of the calling model.

Fit question

Must a reviewer reproduce what expression was submitted, what the resolver returned, and what separate policy authorized later action?

Good fit when
  • At evidence capture, logging, or review boundaries where semantic decisions must be reproducible.
  • A model-generated label can be difficult to reproduce or defend later.

Do not use this recipe when

  • The system would retain only a local paraphrase or label instead of the observed resolver evidence.
  • The audit record would conflate semantic identity with action correctness or authorization.

Best placement: At evidence capture, logging, or review boundaries where semantic decisions must be reproducible.

Minimum request

No whole conversation or credentials
{
  "expression": "provenance-aware semantic record",
  "language": "en"
}

Client record

Type: semantic_audit_evidence

Always
  • originalExpressioncopy the exact submitted expression
  • languagecopy the submitted language tag or null when omitted
  • semanticOutcomeresolved, unknown_expression, ambiguous_expression, or request_or_service_error
  • resolverEvidenceretain the complete observed envelope or an immutable reference to it
Resolved only
  • conceptCodecopy data.concept.code exactly
  • registryVersioncopy data.concept.registryVersion exactly
Never store as authority:
  • candidate-derived, model-derived, translated, approximated, empty, or locally constructed ConceptCode
  • authorization inferred from semantic identity

Handle all four branches: resolved, unknown expression, ambiguous expression, and request or service error

resolved

data.status == "resolved" AND data.concept.code is a non-empty string

Concept assignment: copy exact returned code and registryVersion

  1. Retain the complete envelope, exact ConceptCode, registryVersion, original expression, and evidence timestamp.
  2. Link reviewers to the public Concept record while preserving the exact observed response.

unknown expression

data.status == "abstained" AND data.reason == "unknown_expression"

Concept assignment: none

  1. Retain semanticOutcome=unknown_expression and the complete resolver envelope with no ConceptCode fields.
  2. Document that no governed identity was assigned rather than treating the record as incomplete.

ambiguous expression

data.status == "abstained" AND data.reason == "ambiguous_expression"

Concept assignment: none

  1. Retain semanticOutcome=ambiguous_expression and the complete resolver envelope with no ConceptCode fields.
  2. Record any later clarification as a new evidence event rather than overwriting the original ambiguity.

request or service error

HTTP/input/service failure, malformed envelope, unsupported status, or resolved response without a non-empty code

Concept assignment: none

  1. Retain the request/service error evidence with no ConceptCode fields.
  2. Keep retry results as separate events so the audit trail does not erase the failure state.

Separate authorization gate

Does the audit trail separately show who or what authorized the downstream action, under which policy version, and with what result?

Run this check after semantic interpretation and before any side effect.

If denied: Preserve the semantic evidence but do not perform the action.

Provenance supports review; it does not prove that a downstream action was authorized or correct.

Evidence to retain

  • original expression and optional language
  • complete resolver envelope
  • semantic outcome and abstention/error reason
  • exact ConceptCode and registryVersion only when resolved
  • evidence timestamp and client/application version
  • separate authorization evidence and downstream action outcome

How to prove the benefit

Provenance completeness

semantic decisions with original input, complete outcome evidence, and version data / audited semantic decisions

Target: increase toward complete coverage
Reproducible review rate

audits that can reconstruct semantic and authorization gates independently / attempted audits

Target: increase

Benefit evidence

Compare safety and consistency—not raw call volume.

Measure the selected workflow before integration using the same population and review rules whenever practical.

Compare safer consistency, wrong-assignment prevention, clarification quality, provenance completeness, and duplicate reduction; do not optimize for call volume or resolution rate alone.

Important: A higher resolution rate is not evidence of greater benefit. Wrong accepted identity is more harmful than explicit abstention.

Minimum counters

  • resolver calls at the selected durable boundary
  • resolved outcomes
  • unknown outcomes
  • ambiguous outcomes
  • request or service errors
  • wrong accepted identities found by review
  • actions denied by the separate authorization gate

Standard-library examples

Use built-in language features. Add no SDK dependency.

The examples normalize every resolver response into the same fail-closed record and then apply the five recipes. They never infer a code after abstention or treat identity as permission.

Python standard libraryurllib + json only Node.jsBuilt-in fetch only curlTransport and outcome inspection Recipes JSONStrict machine-readable guide

Deployment readiness

The recipes are complete even when a correct result is “no assignment.”

Recipes describe correct client behavior. Positive exact resolution still depends on deployed reviewed registry evidence; unknown, ambiguous, and error branches are complete outcomes, not placeholders.

Generate the full integration kit Inspect the local proof
Positive exact resolution possible
No
Published concepts
0
Reviewed exact expressions
0
Production resolver
reviewed_exact_registry_first