{"$schema":"https://embeddedsemantics.com/schemas/embedded-semantics-use-case-recipes-v1.schema.json","benefitEvidence":{"baseline":"Measure the selected workflow before integration using the same population and review rules whenever practical.","comparison":"Compare safer consistency, wrong-assignment prevention, clarification quality, provenance completeness, and duplicate reduction; do not optimize for call volume or resolution rate alone.","minimumCounters":["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"],"warning":"A higher resolution rate is not evidence of greater benefit. Wrong accepted identity is more harmful than explicit abstention."},"commonContract":{"abstentionRule":"Every abstained result means no ConceptCode assignment.","authorizationRule":"A ConceptCode is semantic metadata only. Evaluate permission and side effects in a separate policy layer.","branchOrder":["transport_and_envelope","resolved_acceptance_predicate","unknown_expression","ambiguous_expression","other_abstention_or_error","separate_authorization"],"clientRecord":{"alwaysFields":["originalExpression","language","semanticOutcome","resolverEvidence"],"resolvedOnlyFields":["conceptCode","registryVersion"],"separateFields":["authorizationOutcome","authorizationPolicyVersion","downstreamActionOutcome"]},"fitQuestion":"Will a durable consumer benefit from a stable governed identity, and can the workflow preserve no-code outcomes?","identityAcceptanceRule":"Accept identity only when data.status == \"resolved\" and data.concept.code is a non-empty string.","minimumRequest":{"optionalFields":["language"],"requiredFields":["expression"],"secretsAllowed":false,"sendMinimumNecessaryText":true},"placementRule":"Resolve once at a durable memory, routing, record, clarification, or audit boundary\u2014not on every conversational turn."},"invariants":["Original human expression remains visible and is never replaced by a code-only record.","Every recipe stores or transmits the observed semantic outcome.","ConceptCode and registryVersion appear only after the explicit resolved acceptance predicate passes.","Unknown, ambiguity, malformed response, and service error remain no-assignment outcomes.","Candidates, similarity, confidence, embeddings, and local-model output are not semantic authority.","Semantic identity never authorizes memory sharing, routing, tool execution, publication, spending, deletion, or another side effect.","The current production resolver remains reviewed-exact registry first."],"readiness":{"note":"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.","positiveResolutionPossible":false,"productionResolver":"reviewed_exact_registry_first","publishedConcepts":0,"reviewedExactExpressions":0},"recipes":[{"audience":["desktop_agent","local_llm","knowledge_application"],"authorizationCheck":{"ifDenied":"Preserve the semantic evidence but do not perform the action.","question":"May this memory be stored, shared, synchronized, or disclosed under the application's separate privacy and access policy?","rule":"Run this check after semantic interpretation and before any side effect."},"bestPlacement":"At the durable-memory write boundary, not on every conversational turn.","branches":{"ambiguous_expression":{"conceptAssignment":"none","match":"data.status == \"abstained\" AND data.reason == \"ambiguous_expression\"","steps":["Store semanticOutcome=ambiguous_expression and no ConceptCode fields.","Ask for the missing context before creating a governed semantic link, or preserve the memory as unresolved."]},"request_or_service_error":{"conceptAssignment":"none","match":"HTTP/input/service failure, malformed envelope, unsupported status, or resolved response without a non-empty code","steps":["Store or report semanticOutcome=request_or_service_error and no ConceptCode fields.","Retry only according to the application's normal transport policy; never infer identity from a failed request."]},"resolved":{"conceptAssignment":"copy exact returned code and registryVersion","match":"data.status == \"resolved\" AND data.concept.code is a non-empty string","steps":["Store the original expression, semanticOutcome=resolved, exact ConceptCode, registryVersion, and resolver evidence.","Use the code as semantic metadata for retrieval or deduplication while keeping the user's wording visible."]},"unknown_expression":{"conceptAssignment":"none","match":"data.status == \"abstained\" AND data.reason == \"unknown_expression\"","steps":["Store the original expression with semanticOutcome=unknown_expression and no ConceptCode fields.","Keep the memory searchable by its original text or local application metadata without claiming governed identity."]}},"clientRecord":{"always":{"language":"copy the submitted language tag or null when omitted","originalExpression":"copy the exact submitted expression","resolverEvidence":"retain the complete observed envelope or an immutable reference to it","semanticOutcome":"resolved, unknown_expression, ambiguous_expression, or request_or_service_error"},"never":["candidate-derived, model-derived, translated, approximated, empty, or locally constructed ConceptCode","authorization inferred from semantic identity"],"recordType":"semantic_memory","resolvedOnly":{"conceptCode":"copy data.concept.code exactly","registryVersion":"copy data.concept.registryVersion exactly"}},"evidenceToRetain":["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"],"fitCheck":{"goodFitWhen":["At the durable-memory write boundary, not on every conversational turn.","The same remembered idea may be expressed differently across sessions and languages."],"notFitWhen":["The text is a transient conversational turn with no durable memory consumer.","The application cannot retain unresolved or ambiguous memory without inventing a code."],"question":"Will this reviewed meaning be written to durable memory and reused across sessions, languages, or models?"},"humanAnchor":"https://embeddedsemantics.com/recipes#multilingual-memory","id":"multilingual-memory","minimumRequest":{"expression":"stable concept identity","language":"en"},"purpose":"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.","safetyBoundary":"The ConceptCode organizes meaning; it does not authorize memory sharing or downstream actions.","successMetrics":[{"calculation":"duplicate semantic categories / reviewed durable memory categories","id":"duplicate-memory-category-rate","name":"Duplicate memory category rate","targetDirection":"decrease without increasing wrong accepted identity"},{"calculation":"unresolved memories retained with explicit outcome / all unresolved memories","id":"unresolved-memory-visibility","name":"Unresolved memory visibility","targetDirection":"increase toward complete visibility"}],"title":"Multilingual agent memory"},{"audience":["desktop_agent","automation_builder","tool_runtime"],"authorizationCheck":{"ifDenied":"Preserve the semantic evidence but do not perform the action.","question":"Is this route and its side effect permitted for this user, application, resource, and current context?","rule":"Run this check after semantic interpretation and before any side effect."},"bestPlacement":"Immediately before a semantic routing decision whose policy already recognizes published codes.","branches":{"ambiguous_expression":{"conceptAssignment":"none","match":"data.status == \"abstained\" AND data.reason == \"ambiguous_expression\"","steps":["Assign no semantic route key and request the smallest distinguishing clarification.","Do not choose among candidates or possible meanings automatically."]},"request_or_service_error":{"conceptAssignment":"none","match":"HTTP/input/service failure, malformed envelope, unsupported status, or resolved response without a non-empty code","steps":["Assign no semantic route key and keep the side effect blocked or use a documented safe default.","Log the transport/input failure separately from semantic outcomes."]},"resolved":{"conceptAssignment":"copy exact returned code and registryVersion","match":"data.status == \"resolved\" AND data.concept.code is a non-empty string","steps":["Copy the exact ConceptCode into the routing input only after the resolved acceptance predicate passes.","Evaluate the independent allow/deny policy before selecting or executing any route."]},"unknown_expression":{"conceptAssignment":"none","match":"data.status == \"abstained\" AND data.reason == \"unknown_expression\"","steps":["Assign no semantic route key and choose a documented non-semantic fallback or human review path.","Do not use a local model's likely label as a replacement ConceptCode."]}},"clientRecord":{"always":{"language":"copy the submitted language tag or null when omitted","originalExpression":"copy the exact submitted expression","resolverEvidence":"retain the complete observed envelope or an immutable reference to it","semanticOutcome":"resolved, unknown_expression, ambiguous_expression, or request_or_service_error"},"never":["candidate-derived, model-derived, translated, approximated, empty, or locally constructed ConceptCode","authorization inferred from semantic identity"],"recordType":"semantic_route_input","resolvedOnly":{"conceptCode":"copy data.concept.code exactly","registryVersion":"copy data.concept.registryVersion exactly"}},"evidenceToRetain":["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"],"fitCheck":{"goodFitWhen":["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."],"notFitWhen":["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."],"question":"Does an already-authorized routing policy need a stable governed semantic key at one decision boundary?"},"humanAnchor":"https://embeddedsemantics.com/recipes#workflow-routing","id":"workflow-routing","minimumRequest":{"expression":"machine-readable representation","language":"en"},"purpose":"A governed ConceptCode can become a stable semantic input to a separately authorized routing policy.","safetyBoundary":"A resolved identity may inform routing but never grants permission to execute a tool.","successMetrics":[{"calculation":"unsupported or ambiguous inputs blocked from semantic routing / all unsupported or ambiguous routing inputs","id":"wrong-route-prevention","name":"Wrong-route prevention","targetDirection":"increase toward complete prevention"},{"calculation":"authorized routes using exact published codes / all semantic routes","id":"policy-code-consistency","name":"Routing policy code consistency","targetDirection":"increase toward complete consistency"}],"title":"Agent and workflow routing"},{"audience":["application_developer","api_designer","data_engineer"],"authorizationCheck":{"ifDenied":"Preserve the semantic evidence but do not perform the action.","question":"May this event or record be emitted to the intended recipient under the separate data-sharing and access policy?","rule":"Run this check after semantic interpretation and before any side effect."},"bestPlacement":"At an API, event, or persistence boundary where semantic metadata is part of the contract.","branches":{"ambiguous_expression":{"conceptAssignment":"none","match":"data.status == \"abstained\" AND data.reason == \"ambiguous_expression\"","steps":["Emit semanticOutcome=ambiguous_expression with no ConceptCode or registryVersion fields.","Require clarification before a receiver treats the record as governed semantic identity."]},"request_or_service_error":{"conceptAssignment":"none","match":"HTTP/input/service failure, malformed envelope, unsupported status, or resolved response without a non-empty code","steps":["Emit or log semanticOutcome=request_or_service_error according to the record contract, with no ConceptCode fields.","Do not silently drop the failure or manufacture semantic metadata."]},"resolved":{"conceptAssignment":"copy exact returned code and registryVersion","match":"data.status == \"resolved\" AND data.concept.code is a non-empty string","steps":["Attach semanticOutcome=resolved, exact ConceptCode, registryVersion, and resolver evidence as metadata.","Keep domain payload, display text, and authorization fields independent from semantic metadata."]},"unknown_expression":{"conceptAssignment":"none","match":"data.status == \"abstained\" AND data.reason == \"unknown_expression\"","steps":["Emit semanticOutcome=unknown_expression with no ConceptCode or registryVersion fields.","Preserve the original expression so receivers can display or review the unresolved meaning."]}},"clientRecord":{"always":{"language":"copy the submitted language tag or null when omitted","originalExpression":"copy the exact submitted expression","resolverEvidence":"retain the complete observed envelope or an immutable reference to it","semanticOutcome":"resolved, unknown_expression, ambiguous_expression, or request_or_service_error"},"never":["candidate-derived, model-derived, translated, approximated, empty, or locally constructed ConceptCode","authorization inferred from semantic identity"],"recordType":"semantic_event_metadata","resolvedOnly":{"conceptCode":"copy data.concept.code exactly","registryVersion":"copy data.concept.registryVersion exactly"}},"evidenceToRetain":["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"],"fitCheck":{"goodFitWhen":["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."],"notFitWhen":["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."],"question":"Will an API, event, or stored record cross a boundary where another system benefits from inspecting the same governed definition?"},"humanAnchor":"https://embeddedsemantics.com/recipes#api-event-interoperability","id":"api-event-interoperability","minimumRequest":{"expression":"semantic interoperability","language":"en"},"purpose":"Attach an exact ConceptCode and registryVersion to a record or event so recipients can inspect the same definition while retaining their own display language.","safetyBoundary":"Do not replace domain data or access-control fields with a ConceptCode.","successMetrics":[{"calculation":"records using the same exact code for the same reviewed meaning / compared resolved records","id":"cross-system-code-consistency","name":"Cross-system code consistency","targetDirection":"increase"},{"calculation":"retired local label mappings / baseline local label mappings","id":"mapping-table-reduction","name":"One-off mapping table reduction","targetDirection":"increase while preserving unresolved records"}],"title":"API, event, and record interoperability"},{"audience":["support_agent","desktop_agent","human_operator"],"authorizationCheck":{"ifDenied":"Preserve the semantic evidence but do not perform the action.","question":"After the meaning is understood, is the proposed next action allowed and approved under the application's separate policy?","rule":"Run this check after semantic interpretation and before any side effect."},"bestPlacement":"At a decision point where choosing the wrong meaning would materially change the next step.","branches":{"ambiguous_expression":{"conceptAssignment":"none","match":"data.status == \"abstained\" AND data.reason == \"ambiguous_expression\"","steps":["Explain that more than one governed interpretation remains possible and assign no ConceptCode.","Ask one targeted question for the missing distinguishing context."]},"request_or_service_error":{"conceptAssignment":"none","match":"HTTP/input/service failure, malformed envelope, unsupported status, or resolved response without a non-empty code","steps":["Explain that the request needs correction or the service could not return a trustworthy semantic result.","Do not present transport success/failure as semantic identity."]},"resolved":{"conceptAssignment":"copy exact returned code and registryVersion","match":"data.status == \"resolved\" AND data.concept.code is a non-empty string","steps":["Explain that a governed identity was found and display the exact code or public definition when useful.","Continue only after any independent action authorization is evaluated."]},"unknown_expression":{"conceptAssignment":"none","match":"data.status == \"abstained\" AND data.reason == \"unknown_expression\"","steps":["Explain that no reviewed registry identity was found and assign no ConceptCode.","Ask for more context only when it would help the user's task; otherwise continue without semantic identity."]}},"clientRecord":{"always":{"language":"copy the submitted language tag or null when omitted","originalExpression":"copy the exact submitted expression","resolverEvidence":"retain the complete observed envelope or an immutable reference to it","semanticOutcome":"resolved, unknown_expression, ambiguous_expression, or request_or_service_error"},"never":["candidate-derived, model-derived, translated, approximated, empty, or locally constructed ConceptCode","authorization inferred from semantic identity"],"recordType":"clarification_state","resolvedOnly":{"conceptCode":"copy data.concept.code exactly","registryVersion":"copy data.concept.registryVersion exactly"}},"evidenceToRetain":["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"],"fitCheck":{"goodFitWhen":["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."],"notFitWhen":["No stable semantic identity is needed for the interaction.","The interface will present a guessed code as authoritative after unknown or ambiguity."],"question":"Would choosing the wrong meaning materially change the assistance, record, route, or next question?"},"humanAnchor":"https://embeddedsemantics.com/recipes#clarification","id":"clarification","minimumRequest":{"expression":"semantic alignment","language":"en"},"purpose":"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.","safetyBoundary":"Do not frame abstention as a defect the local model should override.","successMetrics":[{"calculation":"clarifications producing a reviewed resolved result or explicit preserved uncertainty / all clarification attempts","id":"clarification-resolution-quality","name":"Clarification resolution quality","targetDirection":"increase without forcing resolution"},{"calculation":"material decisions made without resolved identity or explicit no-code handling / material semantic decisions","id":"silent-assumption-rate","name":"Silent semantic assumption rate","targetDirection":"decrease toward zero"}],"title":"Human clarification and safer assistance"},{"audience":["auditor","system_operator","governance_team"],"authorizationCheck":{"ifDenied":"Preserve the semantic evidence but do not perform the action.","question":"Does the audit trail separately show who or what authorized the downstream action, under which policy version, and with what result?","rule":"Run this check after semantic interpretation and before any side effect."},"bestPlacement":"At evidence capture, logging, or review boundaries where semantic decisions must be reproducible.","branches":{"ambiguous_expression":{"conceptAssignment":"none","match":"data.status == \"abstained\" AND data.reason == \"ambiguous_expression\"","steps":["Retain semanticOutcome=ambiguous_expression and the complete resolver envelope with no ConceptCode fields.","Record any later clarification as a new evidence event rather than overwriting the original ambiguity."]},"request_or_service_error":{"conceptAssignment":"none","match":"HTTP/input/service failure, malformed envelope, unsupported status, or resolved response without a non-empty code","steps":["Retain the request/service error evidence with no ConceptCode fields.","Keep retry results as separate events so the audit trail does not erase the failure state."]},"resolved":{"conceptAssignment":"copy exact returned code and registryVersion","match":"data.status == \"resolved\" AND data.concept.code is a non-empty string","steps":["Retain the complete envelope, exact ConceptCode, registryVersion, original expression, and evidence timestamp.","Link reviewers to the public Concept record while preserving the exact observed response."]},"unknown_expression":{"conceptAssignment":"none","match":"data.status == \"abstained\" AND data.reason == \"unknown_expression\"","steps":["Retain semanticOutcome=unknown_expression and the complete resolver envelope with no ConceptCode fields.","Document that no governed identity was assigned rather than treating the record as incomplete."]}},"clientRecord":{"always":{"language":"copy the submitted language tag or null when omitted","originalExpression":"copy the exact submitted expression","resolverEvidence":"retain the complete observed envelope or an immutable reference to it","semanticOutcome":"resolved, unknown_expression, ambiguous_expression, or request_or_service_error"},"never":["candidate-derived, model-derived, translated, approximated, empty, or locally constructed ConceptCode","authorization inferred from semantic identity"],"recordType":"semantic_audit_evidence","resolvedOnly":{"conceptCode":"copy data.concept.code exactly","registryVersion":"copy data.concept.registryVersion exactly"}},"evidenceToRetain":["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"],"fitCheck":{"goodFitWhen":["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."],"notFitWhen":["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."],"question":"Must a reviewer reproduce what expression was submitted, what the resolver returned, and what separate policy authorized later action?"},"humanAnchor":"https://embeddedsemantics.com/recipes#audit-provenance","id":"audit-provenance","minimumRequest":{"expression":"provenance-aware semantic record","language":"en"},"purpose":"A resolved record points to a published definition, reviewed expressions, provenance, and registry version that can be inspected independently of the calling model.","safetyBoundary":"Provenance supports review; it does not prove that a downstream action was authorized or correct.","successMetrics":[{"calculation":"semantic decisions with original input, complete outcome evidence, and version data / audited semantic decisions","id":"provenance-completeness","name":"Provenance completeness","targetDirection":"increase toward complete coverage"},{"calculation":"audits that can reconstruct semantic and authorization gates independently / attempted audits","id":"reproducible-review-rate","name":"Reproducible review rate","targetDirection":"increase"}],"title":"Audit, provenance, and explainability"}],"schema":"embedded-semantics.use-case-recipes.v1","service":{"adoptionGuide":"https://embeddedsemantics.com/api/v1/adoption-guide","canonicalOrigin":"https://embeddedsemantics.com","capabilities":"https://embeddedsemantics.com/api/v1/capabilities","examples":{"curl":"https://embeddedsemantics.com/examples/agent-recipes/curl-resolver.sh","nodeBuiltInFetch":"https://embeddedsemantics.com/examples/agent-recipes/node-recipes.mjs","pythonStandardLibrary":"https://embeddedsemantics.com/examples/agent-recipes/python-stdlib-recipes.py"},"humanGuide":"https://embeddedsemantics.com/recipes","interactionGuide":"https://embeddedsemantics.com/api/v1/interaction-guide","name":"Embedded Semantics","resolve":"https://embeddedsemantics.com/api/v1/resolve","status":"https://embeddedsemantics.com/api/v1/status"},"version":"1.0.0"}