Go from “I understand it” to “my client is ready.”

#!/usr/bin/env python3
"""Embedded Semantics dependency-free adapter.

Default mode is local fixture conformance. Live HTTPS resolution occurs only
when --live is explicitly supplied. This adapter never performs a downstream
action and never constructs a ConceptCode locally.
"""

from __future__ import annotations

import argparse
import json
import urllib.error
import urllib.request
from collections.abc import Mapping
from copy import deepcopy
from pathlib import Path
from typing import Any

RECIPE_ID = "workflow-routing"
DEFAULT_API_ORIGIN = "https://embeddedsemantics.com"
DEFAULT_POLICY_VERSION = "local-readiness-policy-v1"
ALWAYS_FIELDS = ("originalExpression", "language", "semanticOutcome", "resolverEvidence")
IDENTITY_FIELDS = ("conceptCode", "registryVersion")


def build_client_record(expression: str, language: str | None, envelope: object) -> dict[str, Any]:
    record: dict[str, Any] = {
        "originalExpression": expression,
        "language": language,
        "semanticOutcome": "request_or_service_error",
        "resolverEvidence": deepcopy(envelope),
    }
    if not isinstance(envelope, Mapping):
        record["errorKind"] = "malformed_or_unsupported"
        return record
    error = envelope.get("error")
    if error is not None:
        code = error.get("code") if isinstance(error, Mapping) else None
        record["errorKind"] = "service_error" if code == "service_error" else "request_error"
        record["error"] = deepcopy(error)
        return record
    data = envelope.get("data")
    if not isinstance(data, Mapping):
        record["errorKind"] = "malformed_or_unsupported"
        return record
    if data.get("status") == "resolved":
        concept = data.get("concept")
        code = concept.get("code") if isinstance(concept, Mapping) else None
        version = concept.get("registryVersion") if isinstance(concept, Mapping) else None
        if isinstance(code, str) and code.strip() and isinstance(version, str) and version.strip():
            record["semanticOutcome"] = "resolved"
            record["conceptCode"] = code
            record["registryVersion"] = version
            return record
        record["errorKind"] = "malformed_or_unsupported"
        return record
    if data.get("status") == "abstained" and data.get("reason") in {
        "unknown_expression", "ambiguous_expression"
    }:
        record["semanticOutcome"] = data["reason"]
        record["abstentionReason"] = data["reason"]
        return record
    record["errorKind"] = "malformed_or_unsupported"
    return record


def authorization_record(policy_version: str = DEFAULT_POLICY_VERSION) -> dict[str, object]:
    return {
        "outcome": "not_authorized",
        "policyVersion": policy_version,
        "evaluatedSeparately": True,
        "semanticIdentityGrantsPermission": False,
        "sideEffectPerformed": False,
    }


def run_local(fixtures_path: Path) -> dict[str, object]:
    document = json.loads(fixtures_path.read_text(encoding="utf-8"))
    cases = []
    for fixture in document["fixtures"]:
        record = build_client_record(fixture["expression"], fixture.get("language"), fixture["envelope"])
        cases.append({
            "fixtureId": fixture["id"],
            "record": record,
            "authorization": authorization_record(),
            "sideEffectPerformed": False,
        })
    assigned = [case["fixtureId"] for case in cases if all(field in case["record"] for field in IDENTITY_FIELDS)]
    return {
        "schema": "embedded-semantics.adapter-local-result.v1",
        "recipeId": RECIPE_ID,
        "mode": "local-fixtures",
        "networkCalls": 0,
        "sideEffectsPerformed": 0,
        "identityAssignedFixtureIds": assigned,
        "ready": assigned == ["resolved-valid"] and all(
            all(field in case["record"] for field in ALWAYS_FIELDS) and
            (case["fixtureId"] == "resolved-valid" or not any(field in case["record"] for field in IDENTITY_FIELDS))
            for case in cases
        ),
        "cases": cases,
    }


def resolve_live(expression: str, language: str | None, api_origin: str) -> dict[str, object]:
    payload = {"expression": expression}
    if language:
        payload["language"] = language
    url = api_origin.rstrip("/") + "/api/v1/resolve"
    request = urllib.request.Request(
        url,
        data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
        headers={"Content-Type": "application/json", "Accept": "application/json"},
        method="POST",
    )
    try:
        with urllib.request.urlopen(request, timeout=15) as response:
            envelope = json.load(response)
    except (urllib.error.URLError, TimeoutError, ValueError) as exc:
        envelope = {"data": None, "error": {"code": "transport_error", "message": str(exc)}}
    return {
        "mode": "explicit-live-read-only",
        "request": payload,
        "record": build_client_record(expression, language, envelope),
        "authorization": authorization_record(),
        "sideEffectPerformed": False,
    }


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--fixtures", type=Path, default=Path(__file__).resolve().parents[2] / "fixtures.json")
    parser.add_argument("--live", action="store_true", help="Explicitly call the configured HTTPS resolver")
    parser.add_argument("--expression")
    parser.add_argument("--language")
    parser.add_argument("--api-origin", default=DEFAULT_API_ORIGIN)
    args = parser.parse_args()
    if args.live:
        if not args.expression:
            parser.error("--expression is required with --live")
        result = resolve_live(args.expression, args.language, args.api_origin)
    else:
        result = run_local(args.fixtures)
    print(json.dumps(result, ensure_ascii=False, sort_keys=True, indent=2))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env node
/**
 * Embedded Semantics dependency-free adapter.
 *
 * Default mode is local fixture conformance. Live HTTPS resolution occurs only
 * with --live. No downstream side effect or local ConceptCode inference exists.
 */

import { readFile } from "node:fs/promises";
import { fileURLToPath } from "node:url";
import { dirname, resolve } from "node:path";

const RECIPE_ID = "workflow-routing";
const DEFAULT_API_ORIGIN = "https://embeddedsemantics.com";
const POLICY_VERSION = "local-readiness-policy-v1";
const IDENTITY_FIELDS = ["conceptCode", "registryVersion"];
const ALWAYS_FIELDS = ["originalExpression", "language", "semanticOutcome", "resolverEvidence"];

function copyJson(value) {
  return value === undefined ? null : JSON.parse(JSON.stringify(value));
}

export function buildClientRecord(expression, language, envelope) {
  const record = {
    originalExpression: expression,
    language: typeof language === "string" ? language : null,
    semanticOutcome: "request_or_service_error",
    resolverEvidence: copyJson(envelope),
  };
  if (!envelope || Array.isArray(envelope) || typeof envelope !== "object") {
    record.errorKind = "malformed_or_unsupported";
    return record;
  }
  if (envelope.error !== null && envelope.error !== undefined) {
    record.errorKind = envelope.error?.code === "service_error" ? "service_error" : "request_error";
    record.error = copyJson(envelope.error);
    return record;
  }
  const data = envelope.data;
  if (!data || Array.isArray(data) || typeof data !== "object") {
    record.errorKind = "malformed_or_unsupported";
    return record;
  }
  if (data.status === "resolved") {
    const code = data.concept?.code;
    const version = data.concept?.registryVersion;
    if (typeof code === "string" && code.trim() && typeof version === "string" && version.trim()) {
      record.semanticOutcome = "resolved";
      record.conceptCode = code;
      record.registryVersion = version;
      return record;
    }
    record.errorKind = "malformed_or_unsupported";
    return record;
  }
  if (data.status === "abstained" && ["unknown_expression", "ambiguous_expression"].includes(data.reason)) {
    record.semanticOutcome = data.reason;
    record.abstentionReason = data.reason;
    return record;
  }
  record.errorKind = "malformed_or_unsupported";
  return record;
}

function authorizationRecord() {
  return {
    outcome: "not_authorized",
    policyVersion: POLICY_VERSION,
    evaluatedSeparately: true,
    semanticIdentityGrantsPermission: false,
    sideEffectPerformed: false,
  };
}

async function runLocal(fixturesPath) {
  const document = JSON.parse(await readFile(fixturesPath, "utf8"));
  const cases = document.fixtures.map((fixture) => ({
    fixtureId: fixture.id,
    record: buildClientRecord(fixture.expression, fixture.language, fixture.envelope),
    authorization: authorizationRecord(),
    sideEffectPerformed: false,
  }));
  const assigned = cases
    .filter((item) => IDENTITY_FIELDS.every((field) => Object.hasOwn(item.record, field)))
    .map((item) => item.fixtureId);
  return {
    schema: "embedded-semantics.adapter-local-result.v1",
    recipeId: RECIPE_ID,
    mode: "local-fixtures",
    networkCalls: 0,
    sideEffectsPerformed: 0,
    identityAssignedFixtureIds: assigned,
    ready:
      JSON.stringify(assigned) === JSON.stringify(["resolved-valid"]) &&
      cases.every(
        (item) =>
          ALWAYS_FIELDS.every((field) => Object.hasOwn(item.record, field)) &&
          (item.fixtureId === "resolved-valid" || !IDENTITY_FIELDS.some((field) => Object.hasOwn(item.record, field))),
      ),
    cases,
  };
}

async function resolveLive(expression, language, apiOrigin) {
  const payload = { expression };
  if (language) payload.language = language;
  let envelope;
  try {
    const response = await fetch(`${apiOrigin.replace(/\/$/, "")}/api/v1/resolve`, {
      method: "POST",
      headers: { "Content-Type": "application/json", Accept: "application/json" },
      body: JSON.stringify(payload),
      signal: AbortSignal.timeout(15000),
    });
    envelope = await response.json();
  } catch (error) {
    envelope = { data: null, error: { code: "transport_error", message: String(error) } };
  }
  return {
    mode: "explicit-live-read-only",
    request: payload,
    record: buildClientRecord(expression, language ?? null, envelope),
    authorization: authorizationRecord(),
    sideEffectPerformed: false,
  };
}

function parseArgs(argv) {
  const result = { live: false, fixtures: null, expression: null, language: null, apiOrigin: DEFAULT_API_ORIGIN };
  for (let index = 0; index < argv.length; index += 1) {
    const value = argv[index];
    if (value === "--live") result.live = true;
    else if (value === "--fixtures") result.fixtures = argv[++index];
    else if (value === "--expression") result.expression = argv[++index];
    else if (value === "--language") result.language = argv[++index];
    else if (value === "--api-origin") result.apiOrigin = argv[++index];
    else throw new Error(`Unknown argument: ${value}`);
  }
  return result;
}

const currentDir = dirname(fileURLToPath(import.meta.url));
const args = parseArgs(process.argv.slice(2));
const fixturesPath = args.fixtures ?? resolve(currentDir, "..", "..", "fixtures.json");
if (args.live && !args.expression) throw new Error("--expression is required with --live");
const output = args.live
  ? await resolveLive(args.expression, args.language, args.apiOrigin)
  : await runLocal(fixturesPath);
process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);

# Embedded Semantics dependency-free PowerShell adapter.
# Default mode is Local. Use -Mode Live explicitly for the read-only HTTPS call.
# This script performs no downstream side effect and never constructs a ConceptCode.

[CmdletBinding()]
param(
    [ValidateSet("Local", "Live")]
    [string]$Mode = "Local",
    [string]$FixturesPath = (Join-Path (Split-Path $PSScriptRoot -Parent) "..\fixtures.json"),
    [string]$Expression,
    [string]$Language,
    [string]$ApiOrigin = "https://embeddedsemantics.com"
)

$RecipeId = "workflow-routing"
$PolicyVersion = "local-readiness-policy-v1"
$IdentityFields = @("conceptCode", "registryVersion")
$AlwaysFields = @("originalExpression", "language", "semanticOutcome", "resolverEvidence")

function ConvertTo-PlainObject {
    param([Parameter(Mandatory = $false)]$Value)
    if ($null -eq $Value) { return $null }
    return ($Value | ConvertTo-Json -Depth 100 -Compress | ConvertFrom-Json -AsHashtable)
}

function ConvertTo-ClientRecord {
    param(
        [string]$OriginalExpression,
        [AllowNull()][string]$LanguageTag,
        [Parameter(Mandatory = $false)]$Envelope
    )
    $Evidence = ConvertTo-PlainObject $Envelope
    $Record = [ordered]@{
        originalExpression = $OriginalExpression
        language = $LanguageTag
        semanticOutcome = "request_or_service_error"
        resolverEvidence = $Evidence
    }
    if ($Evidence -isnot [System.Collections.IDictionary]) {
        $Record.errorKind = "malformed_or_unsupported"
        return $Record
    }
    if ($null -ne $Evidence.error) {
        $Record.errorKind = if ($Evidence.error.code -eq "service_error") { "service_error" } else { "request_error" }
        $Record.error = $Evidence.error
        return $Record
    }
    $Data = $Evidence.data
    if ($Data -isnot [System.Collections.IDictionary]) {
        $Record.errorKind = "malformed_or_unsupported"
        return $Record
    }
    if ($Data.status -eq "resolved") {
        $Code = $Data.concept.code
        $Version = $Data.concept.registryVersion
        if (-not [string]::IsNullOrWhiteSpace($Code) -and -not [string]::IsNullOrWhiteSpace($Version)) {
            $Record.semanticOutcome = "resolved"
            $Record.conceptCode = $Code
            $Record.registryVersion = $Version
            return $Record
        }
        $Record.errorKind = "malformed_or_unsupported"
        return $Record
    }
    if ($Data.status -eq "abstained" -and $Data.reason -in @("unknown_expression", "ambiguous_expression")) {
        $Record.semanticOutcome = $Data.reason
        $Record.abstentionReason = $Data.reason
        return $Record
    }
    $Record.errorKind = "malformed_or_unsupported"
    return $Record
}

function New-AuthorizationRecord {
    return [ordered]@{
        outcome = "not_authorized"
        policyVersion = $PolicyVersion
        evaluatedSeparately = $true
        semanticIdentityGrantsPermission = $false
        sideEffectPerformed = $false
    }
}

function Invoke-LocalFixtureTest {
    $Document = Get-Content -LiteralPath $FixturesPath -Raw -Encoding UTF8 | ConvertFrom-Json -AsHashtable
    $Cases = @()
    foreach ($Fixture in $Document.fixtures) {
        $Record = ConvertTo-ClientRecord -OriginalExpression $Fixture.expression -LanguageTag $Fixture.language -Envelope $Fixture.envelope
        $Cases += [ordered]@{
            fixtureId = $Fixture.id
            record = $Record
            authorization = New-AuthorizationRecord
            sideEffectPerformed = $false
        }
    }
    $Assigned = @($Cases | Where-Object {
        $_.record.Contains("conceptCode") -and $_.record.Contains("registryVersion")
    } | ForEach-Object { $_.fixtureId })
    $Ready = ($Assigned.Count -eq 1 -and $Assigned[0] -eq "resolved-valid")
    foreach ($Case in $Cases) {
        foreach ($Field in $AlwaysFields) {
            if (-not $Case.record.Contains($Field)) { $Ready = $false }
        }
        if ($Case.fixtureId -ne "resolved-valid") {
            foreach ($Field in $IdentityFields) {
                if ($Case.record.Contains($Field)) { $Ready = $false }
            }
        }
    }
    return [ordered]@{
        schema = "embedded-semantics.adapter-local-result.v1"
        recipeId = $RecipeId
        mode = "local-fixtures"
        networkCalls = 0
        sideEffectsPerformed = 0
        identityAssignedFixtureIds = $Assigned
        ready = $Ready
        cases = $Cases
    }
}

function Invoke-LiveResolution {
    if ([string]::IsNullOrWhiteSpace($Expression)) { throw "-Expression is required with -Mode Live" }
    $Payload = [ordered]@{ expression = $Expression }
    if (-not [string]::IsNullOrWhiteSpace($Language)) { $Payload.language = $Language }
    try {
        $Envelope = Invoke-RestMethod -Method Post -Uri ($ApiOrigin.TrimEnd("/") + "/api/v1/resolve") `
            -ContentType "application/json; charset=utf-8" -Body ($Payload | ConvertTo-Json -Compress) -TimeoutSec 15
    }
    catch {
        $Envelope = [ordered]@{ data = $null; error = [ordered]@{ code = "transport_error"; message = $_.Exception.Message } }
    }
    return [ordered]@{
        mode = "explicit-live-read-only"
        request = $Payload
        record = ConvertTo-ClientRecord -OriginalExpression $Expression -LanguageTag $Language -Envelope $Envelope
        authorization = New-AuthorizationRecord
        sideEffectPerformed = $false
    }
}

$Result = if ($Mode -eq "Live") { Invoke-LiveResolution } else { Invoke-LocalFixtureTest }
$Result | ConvertTo-Json -Depth 100

#!/bin/sh
set -eu

API_ORIGIN="${EMBEDDED_SEMANTICS_API_ORIGIN:-https://embeddedsemantics.com}"

if [ "${1:-}" != "--live" ]; then
  cat <<'EOF'
This transport example is safe by default and makes no network call.

Run the included Python, Node.js, or PowerShell adapter with no arguments to
exercise all six local fixtures. To make one explicit read-only live request:

  ./adapters/curl/resolve.sh --live "stable concept identity" en

A successful HTTP response is not itself semantic success. Accept identity only
when data.status is "resolved" and both concept.code and registryVersion are
non-empty. Every other branch is no ConceptCode assignment. Authorization is
separate and this script performs no downstream action.
EOF
  exit 0
fi

EXPRESSION="${2:-}"
LANGUAGE="${3:-}"
if [ -z "$EXPRESSION" ]; then
  echo "expression is required" >&2
  exit 2
fi

PAYLOAD=$(python3 - "$EXPRESSION" "$LANGUAGE" <<'PY_PAYLOAD'
import json, sys
payload = {"expression": sys.argv[1]}
if sys.argv[2]:
    payload["language"] = sys.argv[2]
print(json.dumps(payload, ensure_ascii=False, separators=(",", ":")))
PY_PAYLOAD
)

curl --fail-with-body --silent --show-error \
  --max-time 15 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data "$PAYLOAD" \
  "$API_ORIGIN/api/v1/resolve"
printf '\n'